home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / clipper / rlib20.zip / RLIB.DOC < prev    next >
Text File  |  1990-01-02  |  154KB  |  4,820 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.                                         RLIB
  25.                                      Version 2.0
  26.                                   February 18, 1989
  27.  
  28.  
  29.               Useful Functions for the Clipper Applications Programmer
  30.  
  31.  
  32.  
  33.  
  34.  
  35.                           Copyright 1988, 1989 Richard Low
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.                                   TABLE OF CONTENTS
  44.                                   -----------------
  45.  
  46.  
  47.  
  48.        COPYRIGHT AND TRADEMARK NOTICES . . . . . . . . . . . . . . . . . .   4
  49.  
  50.        DISCLAIMER  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   5
  51.  
  52.        CONTENTS OF RLIB PACKAGE  . . . . . . . . . . . . . . . . . . . . .   6
  53.  
  54.        INTRODUCTION  . . . . . . . . . . . . . . . . . . . . . . . . . . .   7
  55.  
  56.        FUNCTION SUMMARY  . . . . . . . . . . . . . . . . . . . . . . . . .   9
  57.  
  58.        ALPHABETICAL LISTING  . . . . . . . . . . . . . . . . . . . . . . .  10
  59.  
  60.        ABOUT SHAREWARE AND REGISTRATION  . . . . . . . . . . . . . . . . .  12
  61.  
  62.        WHAT YOU GET  . . . . . . . . . . . . . . . . . . . . . . . . . . .  13
  63.  
  64.        RLIB REGISTRATION FORM  . . . . . . . . . . . . . . . . . . . . . .  14
  65.  
  66.        LINKING RLIB INTO YOUR APPLICATION  . . . . . . . . . . . . . . . .  15
  67.  
  68.        MODIFYING THE RLIB LIBRARY  . . . . . . . . . . . . . . . . . . . .  16
  69.  
  70.  
  71.        RLIB FUNCTIONS
  72.  
  73.        ALPHADATE() . . . . . . . . . . . . . . . . . . . . . . . . . . . .  18
  74.  
  75.        ATINSAY() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  19
  76.  
  77.        BARMENU() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  21
  78.  
  79.        BEEP()  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  25
  80.  
  81.        BOXASK()  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  26
  82.  
  83.        BOXMENU() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  28
  84.  
  85.        BRIGHT()  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  31
  86.  
  87.        CENTER()  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  32
  88.  
  89.        CHANGED() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  33
  90.  
  91.        CLOSEAREA() . . . . . . . . . . . . . . . . . . . . . . . . . . . .  35
  92.  
  93.        DECRYPTED() . . . . . . . . . . . . . . . . . . . . . . . . . . . .  37
  94.  
  95.        ENCRYPTED() . . . . . . . . . . . . . . . . . . . . . . . . . . . .  38
  96.  
  97.        _______________________________________________________________________
  98.        RLIB 2.0                                                             2
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.        FILEDATE()  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  39
  108.  
  109.        FILES() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  41
  110.  
  111.        FILETIME()  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  43
  112.  
  113.        FORGET()  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  44
  114.  
  115.        GETPARM() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  45
  116.  
  117.        KEYINPUT()  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  47
  118.  
  119.        MARKREC() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  49
  120.  
  121.        MEMORIZE()  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  52
  122.  
  123.        MREPLACE()  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  54
  124.  
  125.        MULTIMENU() . . . . . . . . . . . . . . . . . . . . . . . . . . . .  56
  126.  
  127.        NAMESPLIT() . . . . . . . . . . . . . . . . . . . . . . . . . . . .  59
  128.  
  129.        NTXKEYVAL() . . . . . . . . . . . . . . . . . . . . . . . . . . . .  60
  130.  
  131.        PARENT()  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  61
  132.  
  133.        PATHTO()  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  62
  134.  
  135.        PDOWNINIT() . . . . . . . . . . . . . . . . . . . . . . . . . . . .  63
  136.  
  137.        PDOWNMENU() . . . . . . . . . . . . . . . . . . . . . . . . . . . .  66
  138.  
  139.        PICKFILE()  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  69
  140.  
  141.        PICKREC() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  71
  142.  
  143.        RJUSTIFY()  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  76
  144.  
  145.        SAYINBOX()  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  77
  146.  
  147.        STR2DATE()  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  79
  148.  
  149.  
  150.        APPENDIX A
  151.  
  152.             RLIB QUICK REFERENCE . . . . . . . . . . . . . . . . . . . . .  80
  153.  
  154.  
  155.  
  156.        _______________________________________________________________________
  157.        RLIB 2.0                                                             3
  158.  
  159.  
  160.  
  161.                            COPYRIGHT AND TRADEMARK NOTICES
  162.                            -------------------------------
  163.  
  164.  
  165.  
  166.        CLIPPER and NANTUCKET are trademarks of Nantucket Corporation.
  167.  
  168.        dBASE, and dBASE III PLUS are trademarks of Ashton-Tate, Inc.
  169.  
  170.        IBM and PC-DOS are trademarks of International Business Machines Corp.
  171.  
  172.        LOTUS and 123 are trademarks of Lotus Development Corporation.
  173.  
  174.        MASM, LIB, MS-DOS, Microsoft, Microsoft Object Linker and Microsoft
  175.        Library Manager are trademarks of Microsoft Corporation.
  176.  
  177.        PLINK86 and PLINK86plus are trademarks of Phoenix Technologies, Ltd.
  178.  
  179.        TLINK and Turbo Link are trademarks of Borland International.
  180.  
  181.        CompuServe is a trademark of CompuServe Incorporated.
  182.  
  183.  
  184.  
  185.  
  186.  
  187.        Any other trademarks of other companies which may appear in this
  188.        documentation are for identification purposes only.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.        _______________________________________________________________________
  216.        RLIB 2.0                                                             4
  217.  
  218.  
  219.  
  220.                                      DISCLAIMER
  221.                                      ----------
  222.  
  223.  
  224.  
  225.             The RLIB function library is provided "as is" without warranty of
  226.        any kind, either expressed or implied, including but not limited to the
  227.        implied warranties of merchantability and fitness for a particular
  228.        purpose.  No representation is made that the RLIB functions will meet
  229.        the users' particular requirements.  The user assumes the entire risk
  230.        associated with the use of the RLIB functions and is solely responsible
  231.        for the use and operation of these functions in any application the
  232.        user distributes which may make use of RLIB functions.
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.        _______________________________________________________________________
  275.        RLIB 2.0                                                             5
  276.  
  277.  
  278.  
  279.                               CONTENTS OF RLIB PACKAGE
  280.                               ------------------------
  281.  
  282.  
  283.  
  284.        Filename            Size    Description
  285.        --------          ------    -----------------------------
  286.        READ.ME              539    Latest information/changes
  287.        CONTENTS.DOC       2,871    Text file listing contents
  288.  
  289.        RLIB.LIB          55,808    The RLIB library
  290.        RLIB.DOC         154,155    RLIB Documentation
  291.        RLIB.MAK           1,159    RLIB make file
  292.        MAKERLIB.BAT          16    Batch file for making the library
  293.        MAKEDEMO.BAT          57    Batch file to compile and link the demo
  294.        DEMO.DBF           1,186    The demo database
  295.        DEMO.DBT          21,504    The associated demo memo file
  296.        DEMO.PRG          33,109    The demo program
  297.        DEMOPROC.PRG      15,144    Procedures for the demo program
  298.  
  299.        RL_ALPHA.PRG         601    Source code for the ALPHADATE() function
  300.        RL_ATINS.PRG         708    Source code for the ATINSAY() function
  301.        RL_BARME.PRG       6,683    Source code for the BARMENU() function
  302.        RL_BEEP.PRG          726    Source code for the BEEP() function
  303.        RL_BOXAS.PRG       4,625    Source code for the BOXASK() function
  304.        RL_BOXME.PRG       6,057    Source code for the BOXMENU() function
  305.        RL_BRIGH.PRG         892    Source code for the BRIGHT() function
  306.        RL_CENTE.PRG         907    Source code for the CENTER() function
  307.        RL_CHANG.PRG       1,871    Source code for the CHANGED() function
  308.        RL_CLOSE.PRG       1,747    Source code for the CLOSEAREA() function
  309.        RL_DECRY.PRG         387    Source code for the DECRYPTED() function
  310.        RL_ENCRY.PRG         521    Source code for the ENCRYPTED() function
  311.        RL_FILED.PRG         563    Source code for the FILEDATE() function
  312.        RL_FILES.PRG         906    Source code for the FILES() function
  313.        RL_FILET.PRG         536    Source code for the FILETIME() function
  314.        RL_FORGE.PRG         850    Source code for the FORGET() function
  315.        RL_GETPA.PRG       1,154    Source code for the GETPARM() function
  316.        RL_KEYIN.PRG       2,989    Source code for the KEYINPUT() function
  317.        RL_MARKR.PRG      10,611    Source code for the MARKREC() function
  318.        RL_MEMOR.PRG       1,761    Source code for the MEMORIZE() function
  319.        RL_MREPL.PRG         919    Source code for the MREPLACE() function
  320.        RL_MULTI.PRG      13,151    Source code for the MULTIMENU() function
  321.        RL_NAMES.PRG       2,459    Source code for the NAMESPLIT() function
  322.        RL_NTXKE.PRG         571    Source code for the NTXKEYVAL() function
  323.        RL_PAREN.PRG       1,554    Source code for the PARENT() function
  324.        RL_PATHT.PRG       1,713    Source code for the PATHTO() function
  325.        RL_PDOWN.PRG      15,334    Source code for the PDOWNMENU() function
  326.        RL_PICKF.PRG       3,316    Source code for the PICKFILE() function
  327.        RL_PICKR.PRG      12,172    Source code for the PICKREC() function
  328.        RL_RJUST.PRG         257    Source code for the RJUSTIFY() function
  329.        RL_SAYIN.PRG       6,131    Source code for the SAYINBOX() function
  330.        RL_STR2D.PRG       1,467    Source code for the STR2DATE() function
  331.  
  332.  
  333.        _______________________________________________________________________
  334.        RLIB 2.0                                                             6
  335.  
  336.  
  337.  
  338.                                     INTRODUCTION
  339.                                     ------------
  340.  
  341.  
  342.  
  343.             RLIB was designed as a collection of tools for the Clipper
  344.        Applications Programmer.  Good applications require a solid, consistent
  345.        user interface.  Creating routines for menus, data entry and editing is
  346.        a time consuming process, one we all hope to avoid on a repetitive
  347.        basis.  So, I have assembled a collection of functions that give a wide
  348.        range of applications-oriented use:  Menus, Dialogue Boxes, Database
  349.        record selection routines, string handling, and much more.
  350.  
  351.             There are several libraries available for Clipper programmers that
  352.        provide indispensable functions and procedures.  Most of these library
  353.        functions are written in C and Assembler and provide access to features
  354.        which are not currently supported in Clipper.  RLIB was not designed to
  355.        provide these types of low level functions, mainly because I am not an
  356.        Assembler or C programmer.  I am a Clipper programmer, and I create
  357.        customized applications programs and systems.  Therefore, I was
  358.        interested in developing a collection of functions to make this job
  359.        faster and above all, consistent.
  360.  
  361.             All of the functions in RLIB are written in the Summer '87 version
  362.        of Clipper.  All of the routines that RLIB utilizes are contained in
  363.        the CLIPPER and EXTEND libraries which are distributed as part of the
  364.        Clipper package.  Clipper has a rich set of commands and functions
  365.        which give programmers many tools to create an almost limitless
  366.        collection of procedures, functions, and applications.  If you are
  367.        curious as to some of the capabilities of Clipper, then check out the
  368.        functions in RLIB.  They are ALL WRITTEN 100% IN CLIPPER!
  369.  
  370.             One distinction between RLIB and several other Clipper libraries
  371.        is that RLIB comes with FULL SOURCE CODE INCLUDED!  The source code
  372.        offers several benefits.  First, you can tailor these functions if you
  373.        so desire.  You can expand (or limit) the operation of functions to
  374.        suit your needs.  If a particular function behaves in a way you would
  375.        like to change, then all you have to do is change it.
  376.  
  377.             Secondly, I hope that this source code may provide some level of
  378.        instruction for those of you who may be starting off with Clipper or
  379.        just want to see what Clipper can do.  I learned to program in Clipper
  380.        the hard way, by making my own mistakes.  But I also read every bit of
  381.        source code I could get my hands on to see how and what can be done. 
  382.        As far as the level of instruction these functions may offer, I make no
  383.        proclamation to being the best Clipper programmer around.  However, I
  384.        have been programming and writing applications in Clipper since I
  385.        purchased my copy of the Winter '85 version.
  386.  
  387.             Thirdly, you too can create your own libraries of functions.  With
  388.        the source code comes a complete explanation on how to build a library
  389.        of Clipper compiled functions using a library manager.
  390.  
  391.  
  392.        _______________________________________________________________________
  393.        RLIB 2.0                                                             7
  394.  
  395.  
  396.  
  397.             So now, fire up Clipper, compile and link the DEMO.PRG program
  398.        included with this package, and get a hands on view of RLIB functions. 
  399.        To easily compile and link DEMO.PRG, just run the MAKEDEMO.BAT compile
  400.        and link batch file provided.
  401.  
  402.             Happy Clippering!
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.        _______________________________________________________________________
  452.        RLIB 2.0                                                             8
  453.  
  454.  
  455.  
  456.                                   FUNCTION SUMMARY
  457.                                   ----------------
  458.  
  459.  
  460.  
  461.             To give you a feeling for the range of uses for the functions in
  462.        RLIB, I have categorized them for your reference.
  463.  
  464.  
  465.        MENU                     SCREEN                   FILE
  466.        --------------           --------------           -------------
  467.        BARMENU()                ATINSAY()                FILEDATE()
  468.        BOXMENU()    *           BOXASK()     *           FILES()
  469.        MULTIMENU()  *           BRIGHT()                 FILETIME()
  470.        PDOWNMENU()  *           CENTER()                 PARENT()
  471.                                 SAYINBOX()   *           PATHTO()
  472.                                                          PICKFILE()
  473.  
  474.  
  475.  
  476.  
  477.  
  478.        CHARACTER                DATABASE                 MISCELLANEOUS
  479.        --------------           --------------           -------------
  480.        DECRYPTED()              CHANGED()                ALPHADATE()
  481.        ENCRYPTED()              CLOSEAREA()              BEEP()
  482.        GETPARM()                FORGET()                 NTXKEYVAL()
  483.        KEYINPUT()               MARKREC()    *
  484.        NAMESPLIT()  *           MEMORIZE()
  485.        RJUSTIFY()               MREPLACE()
  486.        STR2DATE()               PICKREC()    *
  487.  
  488.  
  489.             Several functions deserve particular attention for their
  490.        usefulness.  These functions are noted with an asterisk (*) following
  491.        the function name above.  I consider these to be the 'application
  492.        sellers' and I use them all the time, and they are great!  PICKREC()
  493.        especially is great for designing database add, edit, delete etc.
  494.        routines.
  495.  
  496.             The next page consists of a brief description of the purpose of
  497.        each function.
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.        _______________________________________________________________________
  511.        RLIB 2.0                                                             9
  512.  
  513.  
  514.  
  515.                                 ALPHABETICAL LISTING
  516.                                 --------------------
  517.  
  518.  
  519.  
  520.        ALPHADATE()   Convert a date variable to date character string.
  521.  
  522.        ATINSAY()     At a given screen coordinate SAY an expression IN the
  523.                      color setting provided.
  524.  
  525.        BARMENU()     Create Lotus 123 style light bar menus.
  526.  
  527.        BEEP()        Ring the system bell multiple times.
  528.  
  529.        BOXASK()      Pop up a dialogue box in the center of the screen to get
  530.                      user response.
  531.  
  532.        BOXMENU()     Create 'boxed' menus with total control!
  533.  
  534.        BRIGHT()      Get the bright version of the current or indicated color.
  535.  
  536.        CENTER()      Determine the column position to center text on an 80
  537.                      column display, optionally displaying it.
  538.  
  539.        CHANGED()     Determine if field memory variables were changed during
  540.                      an edit.
  541.  
  542.        CLOSEAREA()   Close multiple database work areas with one command.
  543.  
  544.        DECRYPTED()   Un-encrypt a character string encrypted with ENCRYPTED().
  545.  
  546.        ENCRYPTED()   Encrypt a character string.
  547.  
  548.        FILEDATE()    Get the last update date for a file.
  549.  
  550.        FILES()       Determine if multiple files exist with one function.
  551.  
  552.        FILETIME()    Get the last update time for a file.
  553.  
  554.        FORGET()      Release field memory variables created with MEMORIZE().
  555.  
  556.        GETPARM()     Retrieve a comma delimited parameter from a character
  557.                      string.
  558.  
  559.        KEYINPUT()    Get keyboard input while echoing dots on the screen.
  560.  
  561.        MARKREC()     Select multiple database records to process from a pop-up
  562.                      selection window.
  563.  
  564.        MEMORIZE()    Save all field values to memory variables for edit.
  565.  
  566.  
  567.  
  568.  
  569.        _______________________________________________________________________
  570.        RLIB 2.0                                                             10
  571.  
  572.  
  573.  
  574.  
  575.        MREPLACE()    Replace database fields with field memory variables
  576.                      created with MEMORIZE().
  577.  
  578.        MULTIMENU()   Create multi-column menus allowing left, right, up, and
  579.                      down cursor movement to select.
  580.  
  581.        NAMESPLIT()   Convert names in the form First Middle Last to Last,
  582.                      First Middle.
  583.  
  584.        NTXKEYVAL()   Get the controlling index key value for the current
  585.                      record.
  586.  
  587.        PARENT()      Get the parent directory name for the current or supplied
  588.                      directory.
  589.  
  590.        PATHTO()      Search the DOS path for the path leading to a given
  591.                      filename.
  592.  
  593.        PICKFILE()    Pop up a file directory listing to pick a file and return
  594.                      the filename.
  595.  
  596.        PICKREC()     Pop up a menu of database records from which to pick a
  597.                      record.
  598.  
  599.        PULLDOWN()    Create "pull down" menus.
  600.  
  601.        RJUSTIFY()    Right justify character strings by moving trailing blanks
  602.                      to the front.
  603.  
  604.        SAYINBOX()    Easily display messages in the center of the screen in a
  605.                      dialogue box.
  606.  
  607.        STR2DATE()    Convert dates in the form January 31, 1988 to 01/31/88.
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.        _______________________________________________________________________
  629.        RLIB 2.0                                                             11
  630.  
  631.  
  632.  
  633.                           ABOUT SHAREWARE AND REGISTRATION
  634.                           --------------------------------
  635.  
  636.  
  637.  
  638.             For me, shareware is a wonderful concept.  The concept is to allow
  639.        easy access to the widest array of software which can be evaluated at
  640.        no cost.  It is called shareware because it is meant to be shared, or
  641.        distributed, by users via floppy disk and/or electronic bulletin boards
  642.        so that an ever increasing number of people can obtain access to it. 
  643.        The person evaluating this software does not have to shell out any
  644.        money to try it, unlike most commercial packages.  Who wants to lay out
  645.        $500.00, $100.00, or even $35.00 just to look at or try software that
  646.        may or may not fit your needs?  Shareware enables you to try it, and if
  647.        you like it, to buy it.  It's that simple.. a wonderful idea.
  648.  
  649.             However, this does not mean that shareware is free!  If you like
  650.        what you have tried, and intend on using it, you should purchase that
  651.        software.
  652.  
  653.             I have spent much time and effort creating and documenting these
  654.        functions.  While the driving force behind this effort is to share what
  655.        I think are really useful Clipper functions and to demonstrate that a
  656.        myriad of nifty things can be done in Clipper, I am also putting forth
  657.        this effort with the prospect of selling the fruits of my labor.  So,
  658.        if you like these functions, and find them of use and plan on using
  659.        them, you need to complete the registration form on the next page and
  660.        send it in with your payment of $35.00 to purchase your copy of RLIB. 
  661.        With your payment you will become a registered user entitling you to
  662.        free updates and new releases.  Also, registered users are entitled to
  663.        free support if you have any questions or problems with any of the RLIB
  664.        functions.
  665.  
  666.             Under this shareware concept, please feel free to distribute
  667.        copies of RLIB to whomever you wish.   The only restrictions are that: 
  668.        1.  You may not distribute RLIB in any modified form, but only in the
  669.        original format as received by you.   2. You may not charge any fee for
  670.        RLIB or its distribution.   3.  You must distribute all files and parts
  671.        of RLIB as referenced in this document.
  672.  
  673.  
  674.  
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.  
  687.        _______________________________________________________________________
  688.        RLIB 2.0                                                             12
  689.  
  690.  
  691.  
  692.                                     WHAT YOU GET
  693.                                     ------------
  694.  
  695.  
  696.  
  697.             When you purchase RLIB, you get unlimited use of the software. 
  698.        You may compile and link the RLIB functions into your own applications
  699.        and distribute these applications without royalties to the author of
  700.        RLIB.  You may modify the source code to these functions although the
  701.        author cannot support any RLIB function whose source code has been
  702.        changed.
  703.  
  704.             Basically you get unlimited use of the RLIB functions in both
  705.        object code and source code format.  Although the RLIB documentation is
  706.        copyrighted material, the RLIB functions are not so as not to limit
  707.        your ability to freely use them in your applications without having to
  708.        worry about royalties.
  709.  
  710.             You also get support.  Once you purchase your copy of RLIB, feel
  711.        free to contact me regarding any problems you may have with any RLIB
  712.        functions.  The best way to contact me is through CompuServe, or you
  713.        may call me at home.  I also welcome any suggestions or comments you
  714.        may have.
  715.  
  716.             My home address, address, CompuServe ID and home telephone number
  717.        are listed below:
  718.  
  719.  
  720.             Richard Low
  721.             2702 Camellia Street, Apt C
  722.             Durham, NC 27705
  723.  
  724.             CompuServe ID:   72007,1063
  725.             Home telephone:  919-477-0640
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.        _______________________________________________________________________
  747.        RLIB 2.0                                                             13
  748.  
  749.  
  750.  
  751.                                RLIB REGISTRATION FORM
  752.                                ----------------------
  753.  
  754.  
  755.  
  756.        To purchase and register your copy of RLIB please complete the form
  757.        below and mail with your check or money order for $35.00 to:
  758.  
  759.  
  760.  
  761.        RICHARD LOW
  762.        6701 PARKWAY ROAD
  763.        BALTIMORE, MARYLAND 21239
  764.  
  765.  
  766.  
  767.  
  768.  
  769.        Your Full Name:  ________________________________________________
  770.  
  771.  
  772.        Address:         ________________________________________________
  773.  
  774.  
  775.        City:            ________________________________________________
  776.  
  777.  
  778.        State:           _______________________
  779.  
  780.  
  781.        Zip Code:        _______________
  782.  
  783.  
  784.        Home Telephone:  (_______)_______________________
  785.  
  786.  
  787.        Work Telephone:  (_______)_______________________
  788.  
  789.  
  790.        Product: RLIB Version 2.0
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.  
  801.  
  802.  
  803.  
  804.  
  805.        _______________________________________________________________________
  806.        RLIB 2.0                                                             14
  807.  
  808.  
  809.  
  810.                          LINKING RLIB INTO YOUR APPLICATION
  811.                          ----------------------------------
  812.  
  813.  
  814.  
  815.             To include any RLIB functions in your application, you must
  816.        include the RLIB library name in your list of libraries when linking. 
  817.        The only requirement is that you must include the Clipper EXTEND.LIB
  818.        library since RLIB makes use of functions in this library.  Also you
  819.        MUST list RLIB BEFORE EXTEND.LIB so the linker will properly pick up
  820.        the routines.  (Apparently linkers do not make a second pass through
  821.        the libraries to see if a library that follows one on the list calls a
  822.        routine in a preceding one).
  823.  
  824.  
  825.             The syntax for using PLINK86 would be:
  826.  
  827.                   plink86 FILE yourprog LIB clipper,rlib,extend
  828.                                                      ^
  829.                                                      `---------------,
  830.                                                                      |
  831.                                                                      |
  832.             To use MS-LINK, type:                                    |
  833.                                                                      |
  834.                   link yourprog,,,clipper + rlib + extend            |
  835.                                               ^                      |
  836.                                               `----------------------|
  837.                                                                      |
  838.                                                                      |
  839.             To use TLINK, type:                                      |
  840.                                                                      |
  841.                   tlink yourprog,,,clipper + rlib + extend           |
  842.                                                   ^                  |
  843.                                                   `------------------|
  844.                                                                      |
  845.                                                                      |
  846.                                                                      |
  847.                         << YOU MUST LIST RLIB BEFORE EXTEND >>-------'
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.        _______________________________________________________________________
  865.        RLIB 2.0                                                             15
  866.  
  867.  
  868.  
  869.                              MODIFYING THE RLIB LIBRARY
  870.                              --------------------------
  871.  
  872.  
  873.  
  874.        You may want to custom tailor some of the functions in RLIB to meet
  875.        your own needs.  Since the source code is provided for RLIB, this
  876.        capability is what makes RLIB so versatile.  All you need is, of
  877.        course, a copy of Clipper and a library manager program such as LIB
  878.        from Microsoft.  Included with this package is an RLIB.MAK "make" file
  879.        which can be used to maintain and keep the library up to date.  See the
  880.        discussion of how to use a library manager in the documentation that
  881.        comes with the package you use.
  882.  
  883.        When writing a collection of functions to build into a library, the
  884.        biggest difference between Clipper compiled functions and functions
  885.        written in other languages is that Clipper uses the filename to
  886.        identify the function "symbol".  If you have a program named TEST.PRG,
  887.        when you compile it with Clipper, you get a TEST.OBJ file.  That's ok
  888.        if TEST.PRG does something useful, but if all TEST.PRG does is to
  889.        contain a function named TEST, then Clipper will give you a SYMBOL
  890.        REDEFINITION ERROR.  This is because Clipper is trying to create two
  891.        symbols for the linker, both with the same name; one named TEST for the
  892.        .PRG file (program) itself, the other for the function named TEST
  893.        contained in that .PRG file.
  894.  
  895.        For this reason, .PRG files that contain nothing but a function must
  896.        have a name different from the function name itself.  Therefore, all
  897.        the RLIB functions are contained in .PRG files starting with "RL_" and
  898.        ending with the first 5 letters of the function name.  Of course you
  899.        could get around this by having one .PRG file named RLIB.PRG with all
  900.        of the functions separately listed within it, but this nullifies the
  901.        advantage of using a library.  If you did it that way, ALL of the code
  902.        would be linked into your application whether you called all the
  903.        functions within it or not.  Having the functions contained in a
  904.        library is handy because only those functions you use are extracted and
  905.        included in your .EXE file when linked.
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.        _______________________________________________________________________
  924.        RLIB 2.0                                                             16
  925.  
  926.  
  927.  
  928.                                    RLIB FUNCTIONS
  929.                                    ==============
  930.  
  931.  
  932.             The following section contains documentation for each of the RLIB
  933.        functions.  Each function begins on a separate page and provides the
  934.        following information:
  935.  
  936.  
  937.                   Function description
  938.                   Syntax prototype
  939.                   Return value
  940.                   Parameters
  941.                   Usage
  942.                   Behavior
  943.                   Example(s)
  944.                   Source filename
  945.                   Cross references
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.        _______________________________________________________________________
  983.        RLIB 2.0                                                             17
  984.  
  985.  
  986.  
  987.                                      ALPHADATE()
  988.                                      -----------
  989.  
  990.  
  991.  
  992.        This function provides a convenient method of printing a date in the
  993.        form January 1, 1988.  If you print out text date strings often in your
  994.        application, using the following code gets old quick:
  995.  
  996.           CMONTH(date)+' '+LTRIM(STR(DAY(date)))+', '+STR(YEAR(date),4,0)
  997.  
  998.  
  999.        Syntax:
  1000.  
  1001.             ALPHADATE( [date] )
  1002.  
  1003.  
  1004.        Returns:
  1005.  
  1006.             The specified date (or the system date if no parameter was given)
  1007.             as a character string in the form: January 1, 1986.
  1008.  
  1009.  
  1010.        Parameters:
  1011.  
  1012.             date.........  Optional date type variable.  If no parameter is
  1013.                            specified, the current system date is returned.
  1014.  
  1015.  
  1016.        Example:
  1017.  
  1018.             *-- print the current date as a character string
  1019.             ? 'The current date is: ' + ALPHADATE()
  1020.             *-- result = The current date is October 6, 1988
  1021.  
  1022.  
  1023.             *-- print 9/10/87 as a character string
  1024.             datevar = CTOD('09/10/87')
  1025.             @ 5,0 SAY ALPHADATE(datevar)
  1026.             * result = September 10, 1987
  1027.  
  1028.  
  1029.        Source:    RL_ALPHA.PRG
  1030.  
  1031.  
  1032.        See also:  FILEDATE()
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.        _______________________________________________________________________
  1042.        RLIB 2.0                                                             18
  1043.  
  1044.  
  1045.  
  1046.                                       ATINSAY()
  1047.                                       ---------
  1048.  
  1049.  
  1050.  
  1051.        This function takes screen coordinates, a color setting, and a string
  1052.        as parameters, and SAYs the string at the location specified, in the
  1053.        color setting specified.  (AT <coordinates> IN <color> SAY <string>)
  1054.  
  1055.  
  1056.        Syntax:
  1057.  
  1058.             ATINSAY( row, column, color, string )
  1059.  
  1060.  
  1061.        Returns:
  1062.  
  1063.             Nothing useful.
  1064.  
  1065.  
  1066.        Parameters:
  1067.  
  1068.             row..........  Numeric value indicating the row on which to
  1069.                            display <string>.  Value must be between 0 and 24.
  1070.  
  1071.             column.......  Numeric value indicating the column position on
  1072.                            which to display <string>.  Value must be between 0
  1073.                            and 79.
  1074.  
  1075.             color........  Character string indicating the color setting to
  1076.                            use in displaying <string>.  This character string
  1077.                            must be consistent with Clipper's color setting
  1078.                            requirements.  See the Clipper manual under SET
  1079.                            COLOR for details.
  1080.  
  1081.             string.......  The character string to display.
  1082.  
  1083.  
  1084.        Usage:
  1085.  
  1086.             This function is useful if you spend a lot of time SETting COLOR
  1087.             TO and back while @...SAYing messages.  See the example for the
  1088.             code it eliminates.
  1089.  
  1090.  
  1091.        Behavior:
  1092.  
  1093.             This function has a 'black box' design in that it preserves the
  1094.             cursor position and current color setting.  Therefore, you can use
  1095.             it to print strings in different color settings without disrupting
  1096.             either the color or cursor position.
  1097.  
  1098.  
  1099.  
  1100.        _______________________________________________________________________
  1101.        RLIB 2.0                                                             19
  1102.  
  1103.  
  1104.        Example:
  1105.  
  1106.             *-- old way of displaying a message in White on Red, then
  1107.             *-- changing back to White on Black
  1108.             SET COLOR TO w/r
  1109.             @ 24,30 SAY 'A sample message on line 24'
  1110.             SET COLOR TO w/n
  1111.  
  1112.  
  1113.             *-- new way
  1114.             ATINSAY( 24, 30, 'w/r', 'A sample message on line 24' )
  1115.  
  1116.  
  1117.        Source:    RL_ATINS.PRG
  1118.  
  1119.  
  1120.        See also:  BOXASK(), CENTER(), KEYINPUT(), RJUSTIFY(), SAYINBOX()
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130.  
  1131.  
  1132.  
  1133.  
  1134.  
  1135.  
  1136.  
  1137.  
  1138.  
  1139.  
  1140.  
  1141.  
  1142.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.  
  1159.        _______________________________________________________________________
  1160.        RLIB 2.0                                                             20
  1161.  
  1162.  
  1163.  
  1164.                                       BARMENU()
  1165.                                       ---------
  1166.  
  1167.  
  1168.                   
  1169.        BARMENU makes creating horizontal light bar menus a snap.  Although
  1170.        creating this type of menu has been simplified with Clipper's PROMPT
  1171.        and MENU TO commands, this function offers additional flexibility while
  1172.        keeping your code to a minimum.
  1173.  
  1174.  
  1175.        Syntax:
  1176.  
  1177.             BARMENU( row, options [,columns [,choice [,altkeys [,exitkeys;
  1178.                      [,prompts [,prompt_row [,colors ]]]]]]] )
  1179.  
  1180.  
  1181.        Returns:
  1182.  
  1183.             The number of the array element chosen, or zero if the escape key
  1184.             or an exitkey is pressed  (see the discussion of exitkeys below).
  1185.  
  1186.  
  1187.        Parameters:
  1188.  
  1189.             row........... Numeric value indicating the row for the bar menu
  1190.                            to appear.  Value must be between 0 and 24.
  1191.  
  1192.             options....... Array of menu options.  Specify the array name
  1193.                            without quotes to pass this array by reference.
  1194.  
  1195.             columns....... Optional array of column numbers for each menu
  1196.                            choice.  The column numbers in this array must
  1197.                            match the order for the menu options, and each
  1198.                            value must be between 0 and 79.  Specify the array
  1199.                            name without quotes to pass this array by
  1200.                            reference.  If omitted, BARMENU() will place two
  1201.                            columns (spaces) between menu options.
  1202.  
  1203.             choice........ Optional numeric value indicating the starting menu
  1204.                            option number.  Value checked to be between 1 and
  1205.                            the number of elements in the option array.  If an
  1206.                            out of range value is given, the starting number
  1207.                            will be 1.
  1208.  
  1209.             altkeys....... Optional character string indicating what keys may
  1210.                            be pressed to select the corresponding menu option. 
  1211.                            The default 'direct select keys' are the first
  1212.                            letter of each of the menu options, but if this
  1213.                            string is provided, it is added to that list. The
  1214.                            requirement is that the AT() position of the
  1215.                            character in the alternate key list is the numeric
  1216.                            equivalent of the corresponding menu choice.
  1217.  
  1218.        _______________________________________________________________________
  1219.        RLIB 2.0                                                             21
  1220.  
  1221.  
  1222.  
  1223.             exitkeys...... Optional character string indicating which keys if
  1224.                            pressed will cause an exit and return zero.  If
  1225.                            omitted or an empty (or null) string is specified,
  1226.                            then the Escape Key will default to being the only
  1227.                            key to cause a 'return zero exit'.  If this
  1228.                            parameter is specified as a logical .F., then no
  1229.                            keys will cause a return 0 exit (it will be
  1230.                            disabled), and only the Enter Key or a direct
  1231.                            select key will cause an exit condition.
  1232.  
  1233.             prompts....... Optional array of prompt messages corresponding to
  1234.                            each of the menu options.  Specify the array name
  1235.                            without quotes to pass the array by reference.
  1236.  
  1237.             prompt_row.... Optional numeric value indicating the row for the
  1238.                            optional prompt messages to appear.  This value
  1239.                            must be between 0 and 24.  The default is row 24.
  1240.  
  1241.             colors........ Optional array of character strings specifying the
  1242.                            color settings to use.  The colors used for the
  1243.                            different parts of the menu are specified as
  1244.                            follows:
  1245.  
  1246.                                  colors[1] =  Menu choices.
  1247.                                  colors[2] =  Menu selection bar.
  1248.                                  colors[3] =  <not used by BARMENU()>
  1249.                                  colors[4] =  Menu bar line background.
  1250.                                  colors[5] =  Selected choice on exit.
  1251.  
  1252.                            If you use this color feature, DECLARE your colors
  1253.                            array to have at least 5 elements.  If the colors
  1254.                            option is not specified or there are less than 5
  1255.                            elements, then the default colors are used.  These
  1256.                            defaults are: the current Standard color is used
  1257.                            for bar and item displays, and the Enhanced color
  1258.                            is used for the menu bar.
  1259.  
  1260.  
  1261.        Usage:
  1262.  
  1263.             Used to build the horizontal light bar menus that are common in
  1264.             many applications today.
  1265.  
  1266.  
  1267.        Behavior:
  1268.  
  1269.             In addition to the right and left arrow keys, the space bar and
  1270.             back space keys move the menu bar to the right and left.  The menu
  1271.             bar line background (color[4]) is used to clear the menu line and
  1272.             place it in that color.  Like all RLIB functions, if an optional
  1273.             parameter is omitted, but one of the following parameters is used,
  1274.             you must pass a 'dummy' parameter in the place of the omitted
  1275.             parameter.  The best 'dummy' to use is a null string ('').
  1276.  
  1277.        _______________________________________________________________________
  1278.        RLIB 2.0                                                             22
  1279.  
  1280.  
  1281.  
  1282.  
  1283.        Example:
  1284.  
  1285.             *-- present menu choices in a 123 style menu
  1286.  
  1287.  
  1288.             *-- declare arrays for menu and message options
  1289.             DECLARE option[5], prompt[5]
  1290.  
  1291.             *-- menu choices
  1292.             option[1] = 'File' 
  1293.             option[2] = 'Edit'
  1294.             option[3] = 'Next'
  1295.             option[4] = 'Previous'
  1296.             option[5] = 'Quit'
  1297.  
  1298.             *-- corresponding message prompts
  1299.             prompt[1] = 'Load, Save, Transfer, Erase, Quit'
  1300.             prompt[2] = 'New orders, Repairs, Exchanges, Quit'
  1301.             prompt[3] = 'Skip to the next entry'
  1302.             prompt[4] = 'Skip to the previous entry'
  1303.             prompt[5] = 'Quit and return to DOS'
  1304.  
  1305.  
  1306.             *-- set up column position numbers so options fill across screen
  1307.             *-- File         Edit         Next         Previous         Quit
  1308.  
  1309.             *-- if omitted options will look like this:
  1310.             *-- File  Edit  Next  Previous  Quit
  1311.  
  1312.             column[1] =  0
  1313.             column[2] = 18
  1314.             column[3] = 36
  1315.             column[4] = 54
  1316.             column[5] = 76
  1317.  
  1318.             *-- let the down and up arrows also select Next and Previous
  1319.             *-- the AT() position of altkeys in the string must match the
  1320.             *-- corresponding array element number.
  1321.             altkeys = 'FE' + CHR(24) + CHR(5) + 'Q'
  1322.  
  1323.             *-- set up colors to be used
  1324.             DECLARE colors[5]
  1325.             colors[1] = 'B/BG'               && options are Blue on Cyan
  1326.             colors[2] = 'B/W'                && menu bar is Blue on White
  1327.             colors[3] = ''                   && not used
  1328.             colors[4] = 'B/BG'               && menu line also Blue on Cyan
  1329.             colors[5] = 'W+/BG'              && selected option Bright White
  1330.  
  1331.  
  1332.             *-- keep Escape from causing exit, force them to press Q
  1333.             allowexit = .F.
  1334.  
  1335.  
  1336.        _______________________________________________________________________
  1337.        RLIB 2.0                                                             23
  1338.  
  1339.  
  1340.             *-- initial choice = 'File' = 1
  1341.             choice = 1
  1342.  
  1343.             *-- display menu on row 1 with messages on row 2
  1344.             choice = BARMENU( 1, column, option, choice, altkeys,;
  1345.                               allowexit, prompts, 2, colors )
  1346.  
  1347.  
  1348.        Source:    RL_BARME.PRG
  1349.  
  1350.  
  1351.        See also:  BOXMENU(), MULTIMENU(), PDOWNMENU()
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  
  1361.  
  1362.  
  1363.  
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.  
  1395.        _______________________________________________________________________
  1396.        RLIB 2.0                                                             24
  1397.  
  1398.  
  1399.  
  1400.                                        BEEP()
  1401.                                        ------
  1402.  
  1403.  
  1404.  
  1405.        This function merely rings the system bell the specified number of
  1406.        times.  It is useful in replacing the sequence ?? CHR(7) + CHR(7) +
  1407.        CHR(7) with BEEP(3). (I admit, it's not very sophisticated, but I use
  1408.        it all the time!)
  1409.  
  1410.  
  1411.        Syntax: 
  1412.  
  1413.             BEEP( [number] )
  1414.  
  1415.  
  1416.        Returns: 
  1417.  
  1418.             Nothing useful, it just rings the bell.  However, if you must
  1419.             know, the return value is a null ('')
  1420.  
  1421.  
  1422.        Parameters: 
  1423.  
  1424.             number........ Optional numeric variable specifying the number of
  1425.                            times to ring the bell.  If no parameter is
  1426.                            specified, the bell will be sounded one time.
  1427.  
  1428.  
  1429.        Example:
  1430.  
  1431.             *-- ring the bell
  1432.             BEEP()
  1433.  
  1434.             *-- ring it 10 times
  1435.             BEEP(10)
  1436.  
  1437.  
  1438.        Source:    RL_BEEP.PRG
  1439.  
  1440.  
  1441.        See also:  No relatives.
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.        _______________________________________________________________________
  1455.        RLIB 2.0                                                             25
  1456.  
  1457.  
  1458.  
  1459.                                       BOXASK()
  1460.                                       --------
  1461.  
  1462.  
  1463.  
  1464.        BOXASK presents a painless way to pop up a dialogue box in the center
  1465.        of the screen to ask for a keypress response.  The intended use is for
  1466.        displaying error messages of some sort while usually asking if they
  1467.        want to continue.  Up to nine lines may be included with the color used
  1468.        for the box being optional.
  1469.  
  1470.  
  1471.        Syntax:
  1472.  
  1473.             BOXASK( [color,] line1 [,line2 .... ,line9] [,timeout] )
  1474.  
  1475.  
  1476.        Returns:
  1477.  
  1478.             The character pressed or a null string ("") if timed out.
  1479.  
  1480.  
  1481.        Parameters:
  1482.  
  1483.             color......... Optional variable or constant indicating the screen
  1484.                            color setting to use in the form required by
  1485.                            Clipper (e.g. 'W/N').  If omitted, the current
  1486.                            color setting is used.
  1487.  
  1488.             line1......... Character string to be displayed within the box. 
  1489.                            The string may be up to 65 characters long.
  1490.  
  1491.             line2..9...... Optional additional lines to be displayed.  Up to
  1492.                            nine lines may be included, each up to 65
  1493.                            characters in length.
  1494.  
  1495.             timeout....... Optional numeric value indicating the number of
  1496.                            seconds to wait for a response before "timing out"
  1497.                            and returning a null string.  If omitted, the
  1498.                            default wait time is forever.
  1499.  
  1500.  
  1501.        Behavior:
  1502.  
  1503.             The character that is returned is converted to upper case (if it
  1504.             is between 'a' and 'z').  BOXASK() is capable of returning any
  1505.             ASCII character even control characters, the character returned
  1506.             will be the CHR() equivalent of the INKEY() pressed.
  1507.  
  1508.             This is one of the few functions that breaks the rule that says,
  1509.             if you want to skip a parameter, you must pass a dummy in its
  1510.             place.  In this function, the first parameter is evaluated to
  1511.             determine if it is a string to be displayed in the box, or if it
  1512.  
  1513.        _______________________________________________________________________
  1514.        RLIB 2.0                                                             26
  1515.  
  1516.  
  1517.             is a color setting.  The first parameter is deemed to be a color
  1518.             setting if the 2nd, 3rd, or 4th character is the '/' character.
  1519.  
  1520.             At least one line must be specified, if the character string is
  1521.             longer than 65 characters, it is truncated.  If the optional
  1522.             timeout parameter is specified the message will remain on screen
  1523.             for that many seconds or until any key is pressed then disappear. 
  1524.             This is useful for displaying messages for several seconds without
  1525.             having to require the user to press a key.
  1526.  
  1527.             The following defaults apply to determine how the box is
  1528.             positioned in the middle of the screen:
  1529.  
  1530.                Centering   -  The box is centered on screen from top to
  1531.                               bottom, and left to right depending on the
  1532.                               number of lines and the widest line.  One blank
  1533.                               line is placed above and below the first and
  1534.                               last line to be displayed, and five spaces are
  1535.                               placed in front of and trailing the widest line
  1536.                               to be displayed.  Each line is centered within
  1537.                               the box.
  1538.  
  1539.                Environment -  The previous screen underneath the box, the
  1540.                               current color setting, and the cursor position
  1541.                               are saved and restored on exit (after a
  1542.                               keypress).  In other words, the box disappears
  1543.                               and you are left where you were.
  1544.  
  1545.  
  1546.        Example:
  1547.  
  1548.             *-- during a memory save, warn user of existing file and ask if
  1549.             *-- they want to overwrite it, and wait one minute for a response
  1550.             IF FILE('config.mem')
  1551.                line1 = '*** WARNING ***'
  1552.                line2 = 'The file CONFIG.MEM already exists!'
  1553.                line3 = 'Overwrite it? (Y/N)'
  1554.                *-- use a warning color Yellow on Red and wait 60 seconds
  1555.                IF BOXASK('GR+/R', line1, line2, line3, 60 ) = 'Y'
  1556.                   SAVE TO config.mem ALL LIKE cfg_*
  1557.                ENDIF
  1558.             ENDIF
  1559.  
  1560.  
  1561.        Source:    RL_BOXAS.PRG
  1562.  
  1563.  
  1564.        See also:  SAYINBOX()
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.        _______________________________________________________________________
  1573.        RLIB 2.0                                                             27
  1574.  
  1575.  
  1576.  
  1577.                                       BOXMENU()
  1578.                                       ---------
  1579.  
  1580.  
  1581.                   
  1582.        BOXMENU combines the usefulness of Clipper's ACHOICE() function and
  1583.        MENU TO command to give you a convenient way to pop up menus in a box. 
  1584.        Some of the features of BOXMENU are: automatic highlighting of the
  1585.        selected option, automatic 'dulling' of the menu box when finished, and
  1586.        multiple valid 'option' strings to allow not only the first letter of
  1587.        the options to be picked, but a list of option letters you pass as a
  1588.        parameter.
  1589.  
  1590.  
  1591.        Syntax:
  1592.  
  1593.             BOXMENU( row, column, options [, choice [, altkeys [, exitkeys;
  1594.                     [, prompts [, prompt_row [, colors ]]]]]] )
  1595.  
  1596.  
  1597.        Returns:
  1598.  
  1599.             The number of the array element chosen, or zero if the escape key
  1600.             or an exitkey is pressed  (see the discussion of exitkeys below).
  1601.  
  1602.  
  1603.        Parameters:
  1604.  
  1605.             row..........  Numeric value indicating the row for the top left
  1606.                            corner of the menu box.  Value must be between 0
  1607.                            and 24.
  1608.  
  1609.             column.......  Numeric value indicating the column for the top
  1610.                            left corner of the menu box. The value must be
  1611.                            between 0 and 79.
  1612.  
  1613.             options......  Array of menu options.  Specify the array name
  1614.                            without quotes to pass this array by reference.
  1615.  
  1616.             choice.......  Numeric value indicating the starting menu option
  1617.                            number.  Value checked to be between 1 and the
  1618.                            number of elements in the option array.  If an out
  1619.                            of range value is given, the starting number will
  1620.                            be 1.
  1621.  
  1622.             altkeys......  Optional character string indicating what keys may
  1623.                            be pressed to select the corresponding menu option. 
  1624.                            The default 'direct select keys' is the first
  1625.                            letter of each of the menu options, but if this
  1626.                            string is provided, it is added to that the list.
  1627.                            The requirement is that the AT() position of the
  1628.                            character in the alternate key list is the numeric
  1629.                            equivalent of the corresponding menu choice.
  1630.  
  1631.        _______________________________________________________________________
  1632.        RLIB 2.0                                                             28
  1633.  
  1634.  
  1635.             exitkeys.....  Optional character string indicating which keys if
  1636.                            pressed will cause an exit and return zero.  If
  1637.                            omitted or an empty (or null) string is specified,
  1638.                            then the Escape Key will default to being the only
  1639.                            key to cause a return zero exit.  If this parameter
  1640.                            is specified as a logical .F., then no keys will
  1641.                            cause a return 0 exit (it will be disabled), and
  1642.                            only the Enter Key will cause an exit condition.
  1643.  
  1644.             prompts......  Optional array of prompt messages corresponding to
  1645.                            each of the menu options.  Specify the array name
  1646.                            without quotes to pass the array by reference.
  1647.  
  1648.             prompt_row...  Optional numeric value indicating the row for the
  1649.                            optional prompt messages to appear.  This value
  1650.                            must be between 0 and 24.  The default is row 24.
  1651.  
  1652.             colors.......  Optional array of character strings specifying the
  1653.                            color settings to use.  The colors used for the
  1654.                            different parts of the menu are specified as
  1655.                            follows:
  1656.  
  1657.                               colors[1] =  Menu choices.
  1658.                               colors[2] =  Menu selection bar.
  1659.                               colors[3] =  Active menu box color (on entry).
  1660.                               colors[4] =  Inactive menu box color (on exit).
  1661.                               colors[5] =  Selected choice on exit.
  1662.  
  1663.                            If you use this color feature, DECLARE your colors
  1664.                            array to have at least 5 elements.  If the colors
  1665.                            option is not specified or there are less than 5
  1666.                            elements, then the default colors are used.  These
  1667.                            defaults are: the current Standard color is used
  1668.                            for the box and item displays, and the Enhanced
  1669.                            color is used for the menu bar.
  1670.  
  1671.  
  1672.        Behavior:
  1673.  
  1674.             BOXMENU() follows a popular and logical sequence for producing box
  1675.             style menus.  The active menu is surrounded by a double line box. 
  1676.             When it becomes inactive after a choice is made, the box border
  1677.             changes to a single line to indicate the menu is no longer active. 
  1678.             If the row and or column positions supplied are out of bounds (not
  1679.             between 0 and 24, and 0 and 79) a default row or column of 1 will
  1680.             be used.  Also, since this is mainly a menuing tool, no provision
  1681.             has been made to scroll menu items below the bottom of the menu
  1682.             box.  Consequently, you should consider how many options will be
  1683.             in the menu when determining the top row, as the bottom of the box
  1684.             is calculated by adding the number of options in the array.  If
  1685.             more elements exist in the array than will fit in the box,
  1686.             unpredictable screen displays will occur.  This exclusion was made
  1687.             for the benefit of speed and compactness of code.  If a scrollable
  1688.             menu is needed, use ACHOICE().
  1689.  
  1690.        _______________________________________________________________________
  1691.        RLIB 2.0                                                             29
  1692.  
  1693.  
  1694.  
  1695.  
  1696.        Example:
  1697.  
  1698.             *-- declare arrays for menu and message options
  1699.             DECLARE option[5], message[5]
  1700.  
  1701.             *-- menu choices
  1702.             option[1] = " 1.  Add new records (Append) "
  1703.             option[2] = " 2.  Edit records    (Change) "
  1704.             option[3] = " 3.  Delete records  (Remove) "
  1705.             option[4] = " 4.  Update records  (Modify) "
  1706.             option[5] = " 5.  Quit and return (eXit)   "
  1707.  
  1708.             *-- corresponding messages
  1709.             message[1] = "Add new records to the database"
  1710.             message[2] = "Edit records already in the database"
  1711.             message[3] = "Delete selected records"
  1712.             message[4] = "Update dates of last appointments"
  1713.             message[5] = "Leave this menu and return to previous"
  1714.  
  1715.             *-- in addition to pressing 1,2,3,4, or 5, (default select keys)
  1716.             *-- let the following keys also select the choices
  1717.             alt_keys = 'AEDUQ' + 'ACRMX'
  1718.  
  1719.             DECLARE colors[5]
  1720.             colors[1] = 'N/BG'         && options are Black on Cyan
  1721.             colors[2] = 'W+/GR'        && menu bar is Bright White on Brown
  1722.             colors[3] = 'R+/BG'        && active menu is Bright Red on Cyan
  1723.             colors[4] = 'R/BG'         && in-active is Red on Cyan
  1724.             colors[5] = 'R/BG'         && selected choice is Red on Cyan
  1725.  
  1726.             *-- allow Escape and Left and Right arrow keys to exit
  1727.             exit_keys = CHR(27) + CHR(19) + CHR(4)
  1728.  
  1729.             *-- start with first choice
  1730.             choice = 1
  1731.  
  1732.             *-- put up menu on row 2, column 10, with messages on row 24
  1733.             choice = BOXMENU( 2, 10, option, choice, alt_keys, exit_keys,;
  1734.                               message, 24, colors )
  1735.  
  1736.  
  1737.        Source:    RL_BOXME.PRG
  1738.  
  1739.  
  1740.        See also:  BARMENU(), MULTUMENU(), PDOWNMENU()
  1741.  
  1742.  
  1743.  
  1744.  
  1745.  
  1746.  
  1747.  
  1748.  
  1749.        _______________________________________________________________________
  1750.        RLIB 2.0                                                             30
  1751.  
  1752.  
  1753.  
  1754.                                       BRIGHT()
  1755.                                       --------
  1756.  
  1757.  
  1758.  
  1759.        This function returns the bright color attribute setting for either the
  1760.        current color, or the optionally supplied color parameter.  This is
  1761.        useful for switching around color combinations without having to
  1762.        clutter up your code with all that SUBSTR(SUBSTR(... garbage.
  1763.  
  1764.  
  1765.        Syntax:
  1766.  
  1767.             BRIGHT( [color] )
  1768.  
  1769.  
  1770.        Returns:
  1771.  
  1772.             A character string indicating the bright color setting.  The same
  1773.             as extracting the standard part of the color setting and adding a
  1774.             '+' onto the foreground part.
  1775.  
  1776.  
  1777.        Parameters:
  1778.  
  1779.             color........  Optional character string indicating the color
  1780.                            setting from which to extract the bright portion. 
  1781.                            If omitted, the current color setting (returned by
  1782.                            SETCOLOR()) is used.
  1783.  
  1784.  
  1785.        Behavior:
  1786.  
  1787.             If the standard color setting foreground is white, then BRIGHT()
  1788.             makes the high intensity color Yellow (GR+) instead of bright
  1789.             white.  I personally consider this a better interpretation than
  1790.             'bright brown', which is what yellow is.
  1791.  
  1792.  
  1793.        Example:
  1794.  
  1795.             *-- save incoming color, then get bright portion 
  1796.             save_color = SETCOLOR(BRIGHT())
  1797.  
  1798.             CENTER(10,'*** TRY AGAIN ***')         && see CENTER()
  1799.             SETCOLOR(save_color)                   && restore old color
  1800.  
  1801.  
  1802.        Source:    RL_BRIGH.PRG
  1803.  
  1804.  
  1805.        See also:  GETPARM()
  1806.  
  1807.  
  1808.        _______________________________________________________________________
  1809.        RLIB 2.0                                                             31
  1810.  
  1811.  
  1812.  
  1813.                                       CENTER()
  1814.                                       --------
  1815.  
  1816.  
  1817.  
  1818.        Almost everyone has a function to center text on the screen.  So why
  1819.        should RLIB have one also?  This does just what you think; it takes the
  1820.        string provided, and returns the numeric column position to center the
  1821.        text on an 80 column display.  Only this center can also do the
  1822.        displaying, which helps cut down on wordy code.  See the example below.
  1823.  
  1824.  
  1825.        Syntax:
  1826.  
  1827.             CENTER( [ row, ] string )
  1828.  
  1829.  
  1830.        Returns:
  1831.  
  1832.             Numeric integer value of the column number to center <string> on
  1833.             an 80 column display monitor.
  1834.  
  1835.  
  1836.        Parameters:
  1837.  
  1838.             row..........  Optional numeric value which, if passed, will cause
  1839.                            CENTER to print <string> centered on row number
  1840.                            <row>.  Value checked to be between 0 and 24.
  1841.  
  1842.             string.......  Target character string used to determine center
  1843.                            position, and optionally, to print on row number
  1844.                            <row> if <row> is given as a parameter.
  1845.  
  1846.  
  1847.        Example:
  1848.  
  1849.             *-- this method requires two lines of code and a memvar
  1850.             memvar = 'This is the string to center on row 23'
  1851.             @ 23,CENTER(memvar) SAY memvar
  1852.  
  1853.             *-- or without assigning string to memvar (very wordy)
  1854.             @ 23,CENTER('This is the string to center on row 23') ;
  1855.                     SAY 'This is the string to center on row 23'
  1856.  
  1857.             *-- the simpler way
  1858.             CENTER(23,'This is the string to center on row 23')
  1859.  
  1860.  
  1861.        Source:    RL_CENTE.PRG
  1862.  
  1863.  
  1864.        See also:  ATINSAY()
  1865.  
  1866.  
  1867.        _______________________________________________________________________
  1868.        RLIB 2.0                                                             32
  1869.  
  1870.  
  1871.  
  1872.                                       CHANGED()
  1873.                                       ---------
  1874.  
  1875.  
  1876.  
  1877.        CHANGED is designed to serve as a replacement for the Clipper UPDATED()
  1878.        function when used in conjunction with the MEMORIZE() function.  It may
  1879.        also be used to compare the contents of all fields in a record to
  1880.        previously MEMORIZED() copies to determine if changes have been made to
  1881.        the record since it was MEMORIZED().  Changed tests to see if memory
  1882.        field variables have been changed from the associated field values
  1883.        after an edit.  This works better than Clipper's UPDATED() function
  1884.        because once you test for UPDATED(), the flag is cleared.  So if you go
  1885.        back and READ the data again, in a loop for instance, but do NOT change
  1886.        anything this second time around, UPDATED() will return .F., even
  1887.        though something was changed previously.  Ideally, when testing for
  1888.        UPDATED() you want it to be .T. if any values have changed since the
  1889.        last replace.
  1890.  
  1891.        CHANGED() must be used in conjunction with MEMORIZE(), MREPLACE(), and
  1892.        FORGET() functions.  These functions take all the fields in the current
  1893.        database, and store the field values to memory variables of the same
  1894.        name, prefaced by M->.
  1895.  
  1896.  
  1897.        Syntax:
  1898.  
  1899.             CHANGED()
  1900.  
  1901.  
  1902.        Returns:
  1903.  
  1904.             True (.T.) if any changes made to field variables since the last
  1905.             replace or MEMORIZE().
  1906.  
  1907.  
  1908.        Parameters:
  1909.  
  1910.             None
  1911.  
  1912.  
  1913.        Example:
  1914.  
  1915.             *-- this way will not trap an update on re-read
  1916.             DO WHILE .T.
  1917.                *-- get data
  1918.                @ 1,0 GET M->name
  1919.                @ 2,0 GET M->city
  1920.                @ 3,0 GET M->state
  1921.                READ
  1922.                *-- if changed, this will be true, however, after going back
  1923.                *-- through the second time, UPDATED() will only be true if
  1924.                *-- another change was made.  Pressing Escape the second
  1925.  
  1926.        _______________________________________________________________________
  1927.        RLIB 2.0                                                             33
  1928.  
  1929.  
  1930.                *-- time will not be trapped as UPDATED() will be False.
  1931.                IF UPDATED()
  1932.                   IF LASTKEY() = 27          && escape key
  1933.                      @ 0,60 SAY "Abort edit? (Y/N)"
  1934.                      answer = INKEY(0)
  1935.                      @ 0,60 SAY SPACE(20)
  1936.                      IF .NOT. answer $ "Yy"
  1937.                         LOOP
  1938.                      ENDIF
  1939.                   ENDIF
  1940.                ENDIF
  1941.  
  1942.                *-- CHANGED() will compare all M->memvars with the twin
  1943.                *-- field name to see if any values are different.
  1944.  
  1945.             ENDDO
  1946.  
  1947.  
  1948.  
  1949.             *-- this way will work
  1950.  
  1951.             *-- save all database field data to field variables
  1952.             MEMORIZE()
  1953.  
  1954.             DO WHILE .T.
  1955.                *-- get data (remember to preface memvars with M->)
  1956.                @ 1,0 GET M->name
  1957.                @ 2,0 GET M->city
  1958.                @ 3,0 GET M->state
  1959.                READ
  1960.  
  1961.                *-- changed will catch it no matter how many times
  1962.                *-- you go back through the loop
  1963.                IF CHANGED()
  1964.                   IF LASTKEY() = 27          && escape key
  1965.                      @ 0,60 SAY "Abort edit? (Y/N)"
  1966.                      answer = INKEY(0)
  1967.                      @ 0,60 SAY SPACE(20)
  1968.                      IF .NOT. answer $ "Yy"
  1969.                         LOOP
  1970.                      ENDIF
  1971.                   ENDIF
  1972.                ENDIF
  1973.  
  1974.             ENDDO
  1975.  
  1976.  
  1977.        Source:    RL_CHANG.PRG
  1978.  
  1979.  
  1980.        See also:  MEMORIZE(), MREPLACE(), FORGET()
  1981.  
  1982.  
  1983.  
  1984.  
  1985.        _______________________________________________________________________
  1986.        RLIB 2.0                                                             34
  1987.  
  1988.  
  1989.  
  1990.                                      CLOSEAREA()
  1991.                                      -----------
  1992.  
  1993.  
  1994.  
  1995.        CLOSEAREA allows you to close up to nine database files at one time
  1996.        with one line of code without having to leave the currently selected
  1997.        work area.  This is useful when you have several database files open
  1998.        and you want to close all but one or two of them.  
  1999.  
  2000.        Syntax:
  2001.  
  2002.             CLOSEAREA( [ work_area, work_area ... ] )
  2003.  
  2004.  
  2005.        Returns:
  2006.  
  2007.             True (.T.) if all went as expected, False (.F.) if an error.
  2008.  
  2009.  
  2010.        Parameters:
  2011.  
  2012.             work_area....  Number or Alias name of the work area to close.  If
  2013.                            this parameter is a number, it must be a valid
  2014.                            select area number.  If the parameter is an Alias
  2015.                            name, it must be the correct alias as a character
  2016.                            string.  If no parameters are specified, the 
  2017.                            current work area is closed.
  2018.  
  2019.  
  2020.        Usage:
  2021.  
  2022.             Select area numbers and work area Alias names may be intermixed as
  2023.             parameters.  Up to nine areas may be specified.  If no parameter
  2024.             is given, this will be the same as issuing the USE command,
  2025.             closing the current area.
  2026.  
  2027.  
  2028.        Behavior:
  2029.  
  2030.             CLOSEAREA steps through the work areas specified and issues a USE
  2031.             command to close the database.  After all is finished, control is
  2032.             returned to the selected work area at entry.  A return value of
  2033.             .F. should only occur if an invalid parameter is passed (i.e. a
  2034.             Date, Memo, or Logical type parameter) or if you specify an alias
  2035.             name that does not exist.  Normally an invalid alias name will
  2036.             trigger a TYPE MISMATCH runtime error, so CLOSEAREA tests any
  2037.             alias names for proper existence.
  2038.  
  2039.  
  2040.        Example:
  2041.  
  2042.             If you had seven databases open and wanted to close all but the
  2043.  
  2044.        _______________________________________________________________________
  2045.        RLIB 2.0                                                             35
  2046.  
  2047.  
  2048.             databases in work areas 1 and 3 (aliases SALES and CUSTOMERS), one
  2049.             of the ways to accomplish this task would be with the following
  2050.             code:
  2051.  
  2052.                SELECT 1
  2053.                marker1 = RECNO()
  2054.                SELECT 3
  2055.                marker3 = RECNO()
  2056.                CLOSE DATABASES
  2057.                SELECT 1
  2058.                USE Sales INDEX Sales ALIAS Sales
  2059.                GOTO marker1
  2060.                SELECT 3
  2061.                USE Cust INDEX Cust ALIAS Customers
  2062.                GOTO marker3
  2063.  
  2064.  
  2065.             Another way to do this would be as follows:
  2066.  
  2067.                SELECT 2                && Invoices
  2068.                USE
  2069.                SELECT 4                && Payments
  2070.                USE
  2071.                SELECT 5                && Payables
  2072.                USE
  2073.                SELECT 6                && Inventory
  2074.                USE
  2075.                SELECT 7                && Ledger
  2076.                USE
  2077.  
  2078.             With CLOSEAREA(), the following is a LOT easier and simpler!!!
  2079.  
  2080.                CLOSEAREA(2,4,5,6,7)
  2081.  
  2082.             or:
  2083.  
  2084.                CLOSEAREA( 2, 'Payments', 'Payables', 'Inventory', 'Ledger' )
  2085.  
  2086.  
  2087.        Source:    RL_CLOSE.PRG
  2088.  
  2089.  
  2090.        See also:  No relatives.
  2091.  
  2092.  
  2093.  
  2094.  
  2095.  
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.        _______________________________________________________________________
  2104.        RLIB 2.0                                                             36
  2105.  
  2106.  
  2107.  
  2108.                                      DECRYPTED()
  2109.                                      -----------
  2110.  
  2111.  
  2112.  
  2113.        The is the companion to the ENCRYPTED function that follows and is used
  2114.        to Decrypt strings so encrypted.  See discussion below for ENCRYPTED().
  2115.  
  2116.  
  2117.        Syntax:
  2118.  
  2119.             DECRYPTED( string )
  2120.  
  2121.  
  2122.        Returns:
  2123.  
  2124.             An un-encrypted version of <string> of identical length.
  2125.  
  2126.  
  2127.        Parameters:
  2128.  
  2129.             string.......  The character string to decrypt.
  2130.  
  2131.  
  2132.        Behavior:
  2133.  
  2134.             Strings decrypted with this function must have been encrypted with
  2135.             the companion ENCRYPT function.
  2136.  
  2137.  
  2138.        Example:
  2139.  
  2140.             *-- check a password stored in encrypted format
  2141.             @ 5,0 SAY 'Enter your password:'
  2142.  
  2143.             *-- allow only 40 characters, upper case, and echo dots
  2144.             password = KEYINPUT( 40, .T., .F. )          && see KEYINPUT()
  2145.  
  2146.             USE system.dbf
  2147.             IF .NOT. password == DECRYPTED(pword)
  2148.                SAYINBOX( 'W/R', '*** ACCESS DENIED! ***', 6 )
  2149.                USE
  2150.                RETURN
  2151.             ENDIF
  2152.  
  2153.  
  2154.        Source:    RL_DECRY.PRG
  2155.  
  2156.  
  2157.        See also:  ENCRYPTED(), KEYINPUT(), SAYINBOX()
  2158.  
  2159.  
  2160.  
  2161.  
  2162.        _______________________________________________________________________
  2163.        RLIB 2.0                                                             37
  2164.  
  2165.  
  2166.  
  2167.                                      ENCRYPTED()
  2168.                                      -----------
  2169.  
  2170.  
  2171.  
  2172.        The are several Encrypt/Decrypt functions out there, most of which are
  2173.        written in assembly or C.  This is a simple Encryption scheme done
  2174.        entirely in Clipper which is not only functional, but the source is
  2175.        easily altered to provide unique algorithms.  Data encrypted with this
  2176.        function is Decrypted with the companion DECRYPTED function.
  2177.  
  2178.  
  2179.        Syntax:
  2180.  
  2181.             ENCRYPTED( string )
  2182.  
  2183.  
  2184.        Returns:
  2185.  
  2186.             An encrypted version of <string> of identical length.
  2187.  
  2188.  
  2189.        Parameters:
  2190.  
  2191.             string.......  The character string to encrypt.
  2192.  
  2193.  
  2194.        Behavior:
  2195.  
  2196.             Strings encrypted with this function can only be decrypted with
  2197.             the DECRYPT function, or with an authentic World War II decoder
  2198.             machine.
  2199.  
  2200.  
  2201.        Example:
  2202.  
  2203.             *-- get password, then store in encrypted format
  2204.             @ 5,0 SAY 'Enter your password:'
  2205.             *-- allow only 40 characters, upper case, and echo only dots
  2206.             password = KEYINPUT( 40, .T., .F. )          && see KEYINPUT()
  2207.             USE system.dbf
  2208.             REPLACE pword WITH ENCRYPTED(password)
  2209.  
  2210.  
  2211.        Source:    RL_ENCRY.PRG
  2212.  
  2213.  
  2214.        See also:  DECRYPTED()
  2215.  
  2216.  
  2217.  
  2218.  
  2219.  
  2220.  
  2221.        _______________________________________________________________________
  2222.        RLIB 2.0                                                             38
  2223.  
  2224.  
  2225.  
  2226.                                      FILEDATE()
  2227.                                      ----------
  2228.  
  2229.  
  2230.  
  2231.        This function extracts the date from the given file's directory entry
  2232.        information.  It is useful for comparing the dates of two files, or for
  2233.        using the file date for a variety of purposes.  I have used it in
  2234.        conjunction with FILETIME() to determine if an index file is current
  2235.        with the associated .DBF file.  FILEDATE() simplifies all the ADIR()
  2236.        and associated lines of code to get the file date.
  2237.  
  2238.  
  2239.        Syntax:
  2240.  
  2241.             FILEDATE( filename )
  2242.  
  2243.  
  2244.        Returns:
  2245.  
  2246.             Date from the file's directory entry (last update date).
  2247.  
  2248.  
  2249.        Parameters:
  2250.  
  2251.             filename.....  Character string or variable indicating the name of
  2252.                            the file for which to extract the date.  This
  2253.                            filename (filespec) must and may adhere to any
  2254.                            fully qualified filename as required by ADIR().
  2255.  
  2256.  
  2257.        Usage:
  2258.  
  2259.             If an invalid filename is given, or if the file does not exist,
  2260.             FILEDATE() will return an empty date (  /  /  ).  Beware that if
  2261.             the file being checked is currently open, the date from the
  2262.             directory entry may not reflect updates until the file is closed.
  2263.  
  2264.        Example 1:
  2265.  
  2266.             *-- see if the date and time of the .DBF and .NTX files agree
  2267.             ok = ( FILEDATE('myfile.dbf') == FILEDATE('myfile.ntx') .AND.;
  2268.                    FILETIME('myfile.dbf') == FILETIME('myfile.ntx') )
  2269.             USE myfile INDEX myfile
  2270.             IF .NOT. ok
  2271.                ? 'Please wait, updating index...'
  2272.                REINDEX
  2273.                GO TOP
  2274.             ENDIF
  2275.  
  2276.  
  2277.        Example 2:
  2278.  
  2279.  
  2280.        _______________________________________________________________________
  2281.        RLIB 2.0                                                             39
  2282.  
  2283.  
  2284.             *-- prompt user for file backup request
  2285.             lastback = FILEDATE('myfile.bak')
  2286.             ? 'MYFILE.DBF was last backed up on ' + ALPHADATE(lastback)
  2287.             WAIT 'Do you want to back it up now? (Y/N)' TO answer
  2288.             IF answer $ 'Yy'
  2289.                ERASE myfile.bak
  2290.                COPY FILE myfile.dbf TO myfile.bak
  2291.             ENDIF
  2292.  
  2293.  
  2294.        Source:    RL_FILED.PRG
  2295.  
  2296.  
  2297.        See also:  FILETIME(), FILES()
  2298.  
  2299.  
  2300.  
  2301.  
  2302.  
  2303.  
  2304.  
  2305.  
  2306.  
  2307.  
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313.  
  2314.  
  2315.  
  2316.  
  2317.  
  2318.  
  2319.  
  2320.  
  2321.  
  2322.  
  2323.  
  2324.  
  2325.  
  2326.  
  2327.  
  2328.  
  2329.  
  2330.  
  2331.  
  2332.  
  2333.  
  2334.  
  2335.  
  2336.  
  2337.  
  2338.  
  2339.        _______________________________________________________________________
  2340.        RLIB 2.0                                                             40
  2341.  
  2342.  
  2343.  
  2344.                                        FILES()
  2345.                                        -------
  2346.  
  2347.  
  2348.  
  2349.        This function tests for the existence of multiple files at one time. 
  2350.        It is useful for reducing a wordy FILE() concoctenation.
  2351.  
  2352.  
  2353.        Syntax:
  2354.  
  2355.             FILES( filename [, filename...filename ] )
  2356.  
  2357.  
  2358.        Returns:
  2359.  
  2360.             True if all the specified files exist.
  2361.  
  2362.  
  2363.        Parameters:
  2364.  
  2365.             filename...... Character string or variable of the file to test
  2366.                            for existence.  Up to nine filenames may be given,
  2367.                            separated by commas.
  2368.  
  2369.  
  2370.        Usage:
  2371.  
  2372.             Used in place of a series of FILE() functions .AND.ed together. 
  2373.             If you have to test for more than one file often, this really
  2374.             cleans things up and makes code very readable.
  2375.  
  2376.  
  2377.        Behavior:
  2378.  
  2379.             FILES() uses the Clipper FILE() function to successively test for
  2380.             each file specified.  If any test fails, FILES() returns False. 
  2381.             Since the FILE() function is used, it follows Clippers current SET
  2382.             DEFAULT setting.
  2383.  
  2384.  
  2385.        Example:
  2386.  
  2387.             *-- see if all needed index files exist
  2388.             USE Sales
  2389.  
  2390.             IF FILES( "Custno.ntx",   "Invoice.ntx",;
  2391.                       "Salesman.ntx", "Repair.ntx",;
  2392.                       "Saledate.ntx" )
  2393.                SET INDEX TO Custno, Invoice, Salesman, Repair, Saledate
  2394.             ELSE
  2395.                *-- do indexing
  2396.             ENDIF
  2397.  
  2398.        _______________________________________________________________________
  2399.        RLIB 2.0                                                             41
  2400.  
  2401.  
  2402.  
  2403.             *-- the old way to do it
  2404.             IF FILE("Custno.ntx"  ) .AND. FILE("Invoice.ntx") .AND.;
  2405.                FILE("Salesman.ntx") .AND. FILE("Repair.ntx" ) .AND.;
  2406.                FILE("Saledate.ntx")
  2407.  
  2408.  
  2409.        Source:    RL_FILES.PRG
  2410.  
  2411.  
  2412.        See also:  FILEDATE(), FILETIME()
  2413.  
  2414.  
  2415.  
  2416.  
  2417.  
  2418.  
  2419.  
  2420.  
  2421.  
  2422.  
  2423.  
  2424.  
  2425.  
  2426.  
  2427.  
  2428.  
  2429.  
  2430.  
  2431.  
  2432.  
  2433.  
  2434.  
  2435.  
  2436.  
  2437.  
  2438.  
  2439.  
  2440.  
  2441.  
  2442.  
  2443.  
  2444.  
  2445.  
  2446.  
  2447.  
  2448.  
  2449.  
  2450.  
  2451.  
  2452.  
  2453.  
  2454.  
  2455.  
  2456.  
  2457.        _______________________________________________________________________
  2458.        RLIB 2.0                                                             42
  2459.  
  2460.  
  2461.  
  2462.                                      FILETIME()
  2463.                                      ----------
  2464.  
  2465.  
  2466.  
  2467.        This function extracts the time from the given file's directory entry
  2468.        information.  It is useful for comparing the times of two files, or for
  2469.        using the file time for a variety of purposes.  See the discussion of
  2470.        the associated FILEDATE() function.
  2471.  
  2472.  
  2473.        Syntax:
  2474.  
  2475.             FILETIME( filename )
  2476.  
  2477.  
  2478.        Returns:
  2479.  
  2480.             Time from the file's directory entry as a character string in the
  2481.             form HH:MM:SS (last update time).
  2482.  
  2483.  
  2484.        Parameters:
  2485.  
  2486.             filename.....  Character string or variable indicating the name of
  2487.                            the file for which to extract the time.  This
  2488.                            filename (filespec) must and may adhere to any
  2489.                            fully qualified filename as required by ADIR().
  2490.  
  2491.  
  2492.        Usage:
  2493.  
  2494.             If an invalid filename is given, or if the file does not exist,
  2495.             FILETIME() will return a null string ('').  Beware that if the
  2496.             file being checked is currently open, the directory time may not
  2497.             reflect updates until the file is closed.
  2498.  
  2499.        Example:
  2500.  
  2501.             See examples above for FILEDATE().
  2502.  
  2503.  
  2504.        Source:    RL_FILET.PRG
  2505.  
  2506.  
  2507.        See also:  FILEDATE(), FILES()
  2508.  
  2509.  
  2510.  
  2511.  
  2512.  
  2513.  
  2514.  
  2515.  
  2516.        _______________________________________________________________________
  2517.        RLIB 2.0                                                             43
  2518.  
  2519.  
  2520.  
  2521.                                       FORGET()
  2522.                                       --------
  2523.  
  2524.  
  2525.  
  2526.        This function is designed to be used in conjunction with CHANGED(),
  2527.        MEMORIZE(), and MREPLACE(); they are all a team.  Put together, they
  2528.        simplify the tedious task of making a memory variable copy of each
  2529.        field in a database record to work with  (some languages call them
  2530.        temporary field variables), and then replacing the fields with the
  2531.        associated memory copy after edits.  FORGET() is used to release the
  2532.        PUBLIC variables created by MEMORIZE() when your editing is finished.
  2533.  
  2534.  
  2535.        Syntax:
  2536.  
  2537.             FORGET()
  2538.  
  2539.  
  2540.        Returns:
  2541.  
  2542.             True (.T.) if all fields successively released.
  2543.  
  2544.  
  2545.        Parameters:
  2546.  
  2547.             None.
  2548.  
  2549.  
  2550.        Usage:
  2551.  
  2552.             Since variables created with MEMORIZE() are declared PUBLIC,
  2553.             FORGET() releases them to reclaim memory and to avoid any
  2554.             potential name conflicts.  Some programmers save all field values
  2555.             to memory variables with a common prefix (like x_), and when they
  2556.             are finished with them do a RELEASE ALL LIKE x_*.  This is fine if
  2557.             the variables are released in the same procedure in which they
  2558.             were created.  However, it is more efficient to do this storing in
  2559.             a sub-procedure, hence the need to make these variables PUBLIC. 
  2560.             The problem is that in Clipper, you cannot RELEASE ALL LIKE x_* if
  2561.             the x_* variables are PUBLIC variables that were created in
  2562.             another procedure.  FORGET() takes care of all this by explicitly
  2563.             naming each variable to be RELEASEd, which is the only way you can
  2564.             release a PUBLIC variable created in another procedure.
  2565.  
  2566.  
  2567.        Example:   See examples for MEMORIZE(), CHANGED(), and REPLACED().
  2568.  
  2569.  
  2570.        Source:    RL_FORGE.PRG
  2571.  
  2572.  
  2573.        See also:  CHANGED(), MEMORIZE(), MREPLACE()
  2574.  
  2575.        _______________________________________________________________________
  2576.        RLIB 2.0                                                             44
  2577.  
  2578.  
  2579.  
  2580.                                       GETPARM()
  2581.                                       ---------
  2582.  
  2583.  
  2584.  
  2585.        This function is used to retrieve a comma delimited parameter from a
  2586.        character string.  The ways in which this can be used are unlimited,
  2587.        but as an example, several RLIB functions use GETPARM() to retrieve
  2588.        color settings from the strings provided.
  2589.  
  2590.  
  2591.        Syntax:
  2592.  
  2593.             GETPARM( position, string )
  2594.  
  2595.  
  2596.        Returns:
  2597.  
  2598.             Character string equal to the parameter.
  2599.  
  2600.  
  2601.        Parameters:
  2602.  
  2603.             position...... Numeric value indicating the ordinal position in
  2604.                            the parameter list.
  2605.  
  2606.             string........ The comma delimited string from which to extract
  2607.                            the characters following the <position>-1 comma.
  2608.  
  2609.  
  2610.        Usage:
  2611.  
  2612.             Used RLIB to parse the SETCOLOR() color string for default colors
  2613.             when no color arrays are specified in the functions that offer
  2614.             color as an option.  (You must therefore not remove GETPARM() from
  2615.             RLIB!)
  2616.  
  2617.  
  2618.        Behavior:
  2619.  
  2620.             If there exists no characters at the ordinal position indicated,
  2621.             GETPARM() returns a null string.
  2622.  
  2623.  
  2624.        Example:
  2625.  
  2626.             *-- supply your UDF with several parameters all bunched in
  2627.             *-- one character string
  2628.             files = 'TEST1.DBF, TEST2.DBF, TEST3.DBF, TEST4.DBF, TEST5.DBF'
  2629.  
  2630.             *-- this UDF opens all the files in your string
  2631.             *-- in separate work areas
  2632.             OPENFILES(files)
  2633.  
  2634.        _______________________________________________________________________
  2635.        RLIB 2.0                                                             45
  2636.  
  2637.  
  2638.             .
  2639.             .
  2640.             .
  2641.             *-- now here's your UDF to open many files in one swoop
  2642.             FUNCTION OPENFILES
  2643.             PARAMETERS filenames
  2644.             PRIVATE file2open
  2645.  
  2646.             DO WHILE .T.
  2647.                file2open = GETPARM( x, filenames )
  2648.                IF EMPTY(file2open)
  2649.                   EXIT
  2650.                ENDIF
  2651.                SELECT 0
  2652.                USE &file2open
  2653.             ENDDO
  2654.             RETURN .T.
  2655.  
  2656.  
  2657.        Example #2:
  2658.  
  2659.             *-- get the current Enhanced color setting
  2660.             mreverse = GETPARM( 2, SETCOLOR() )
  2661.  
  2662.  
  2663.        Source:    RL_GETPA.PRG
  2664.  
  2665.  
  2666.        See also:  BRIGHT()
  2667.  
  2668.  
  2669.  
  2670.  
  2671.  
  2672.  
  2673.  
  2674.  
  2675.  
  2676.  
  2677.  
  2678.  
  2679.  
  2680.  
  2681.  
  2682.  
  2683.  
  2684.  
  2685.  
  2686.  
  2687.  
  2688.  
  2689.  
  2690.  
  2691.  
  2692.  
  2693.        _______________________________________________________________________
  2694.        RLIB 2.0                                                             46
  2695.  
  2696.  
  2697.  
  2698.                                      KEYINPUT()
  2699.                                      ----------
  2700.  
  2701.  
  2702.  
  2703.        There is no built in way of allowing key input while echoing dots on
  2704.        the screen to prevent on-lookers from seeing what is being entered. 
  2705.        SETting COLOR TO X will blank out the screen but then you cannot see
  2706.        how many characters have been entered.  We may want to see dots echo
  2707.        (as most BBS' do) so we can tell how many characters we have entered. 
  2708.        With keyinput you can easily do this, while also determining the
  2709.        maximum length of the input string, whether or not it is to be all
  2710.        upper case, and whether or not to echo the actual characters on the
  2711.        screen, or just dots.  Key input starts accepting character input at
  2712.        the current cursor location on the screen and terminates when either
  2713.        the maximum character count has been reached or ENTER is pressed.
  2714.  
  2715.  
  2716.        Syntax:
  2717.  
  2718.             KEYINPUT( length, upper_case, echo_chars )
  2719.  
  2720.  
  2721.        Returns:
  2722.  
  2723.             The character string typed in, or a null string ('') if the Escape
  2724.             key was pressed.
  2725.  
  2726.  
  2727.        Parameters:
  2728.  
  2729.             length.......  Numeric value specifying the maximum allowable
  2730.                            length of the string that may be entered (and
  2731.                            returned by KEYINPUT).  If this value is greater
  2732.                            than the remaining width of the screen, key input
  2733.                            will wrap to the next line.
  2734.  
  2735.             upper_case...  Logical value (.T./.F.) indicating if all
  2736.                            characters inputted will be forced into upper case. 
  2737.                            The default is false, characters will be returned
  2738.                            as entered.
  2739.  
  2740.             echo_chars...  Logical value (.T./.F.) indicating if inputted
  2741.                            characters will appear on the screen.  If this
  2742.                            value is false, dots will echo on screen.  The
  2743.                            default is true, characters will echo on screen.
  2744.  
  2745.  
  2746.        Example:
  2747.  
  2748.             *-- get the user's password, keep it less than or equal to 30
  2749.             *-- characters, make it upper case, and echo dots on the screen
  2750.  
  2751.  
  2752.        _______________________________________________________________________
  2753.        RLIB 2.0                                                             47
  2754.  
  2755.  
  2756.             @ 5,0 SAY 'Enter your password: '
  2757.             password = KEYINPUT( 30, .T., .F. )
  2758.  
  2759.  
  2760.        Source:    RL_KEYIN.PRG
  2761.  
  2762.  
  2763.        See also:  NAMESPLIT()
  2764.  
  2765.  
  2766.  
  2767.  
  2768.  
  2769.  
  2770.  
  2771.  
  2772.  
  2773.  
  2774.  
  2775.  
  2776.  
  2777.  
  2778.  
  2779.  
  2780.  
  2781.  
  2782.  
  2783.  
  2784.  
  2785.  
  2786.  
  2787.  
  2788.  
  2789.  
  2790.  
  2791.  
  2792.  
  2793.  
  2794.  
  2795.  
  2796.  
  2797.  
  2798.  
  2799.  
  2800.  
  2801.  
  2802.  
  2803.  
  2804.  
  2805.  
  2806.  
  2807.  
  2808.  
  2809.  
  2810.  
  2811.        _______________________________________________________________________
  2812.        RLIB 2.0                                                             48
  2813.  
  2814.  
  2815.  
  2816.                                       MARKREC()
  2817.                                       ---------
  2818.  
  2819.  
  2820.  
  2821.        MARKREC() lets a user select multiple records from a database to be
  2822.        included in some subsequent operation.  One such use is for prompting
  2823.        the user for records to include in a report.  They cursor up and down
  2824.        through a menu consisting of field expressions, and press a designated
  2825.        mark key to select the record.  When the user terminates by pressing
  2826.        the Enter key, MARKREC() returns a list of record numbers or field
  2827.        contents of the records selected.
  2828.  
  2829.  
  2830.        Syntax:
  2831.  
  2832.             MARKREC( top, left, bottom, right, output [, markkey 
  2833.                      [, markfield  [, colors ] ] ] )
  2834.  
  2835.  
  2836.        Returns:
  2837.  
  2838.             A character string consisting of selected "markfield" data, or the
  2839.             default of selected record numbers, each eight digits long,
  2840.             delimited with a comma ",", or a null string if Escape was
  2841.             pressed.
  2842.  
  2843.  
  2844.        Parameters:
  2845.  
  2846.             top........... Numeric values specifying the window coordinates
  2847.             left.......... of the 'display box'.  The top and bottom values
  2848.             bottom........ must be between 0 and 24, and the left and right
  2849.             right......... coordinates must be between 0 and 79.
  2850.  
  2851.             output........ Character expression which evaluates to a field
  2852.                            list to be displayed at runtime.  This value is
  2853.                            used as a macro substitution, so it must evaluate
  2854.                            correctly to a character string.
  2855.  
  2856.             markkey....... Optional numeric value indicating which key will
  2857.                            act as the 'marker' key.  This value is equal to
  2858.                            the ASCII INKEY() value of the key.  If omitted or
  2859.                            an invalid parameter is supplied, the default value
  2860.                            is -8 which is the INKEY() value for the F9 key.
  2861.  
  2862.             markfield..... The field name (or expression) as a character
  2863.                            string, indicating the data to be extracted and
  2864.                            placed into the "pick list".  This field or
  2865.                            expression must evaluate to a character string.  If
  2866.                            no parameter is supplied, or an invalid parameter
  2867.                            (such as a dummy), the default markfield is the
  2868.                            record number as an 8 digit character string.
  2869.  
  2870.        _______________________________________________________________________
  2871.        RLIB 2.0                                                             49
  2872.  
  2873.  
  2874.  
  2875.             colors........ Optional array of character strings specifying the
  2876.                            color settings to use.
  2877.  
  2878.                               colors[1] = Standard color for un-marked records
  2879.                               colors[2] = Standard color for marked records
  2880.                               colors[3] = Highlite color for un-marked records
  2881.                               colors[4] = Highlite color for marked records
  2882.  
  2883.                            If you use this color feature, DECLARE your colors
  2884.                            array to have at least 4 elements.  If the colors
  2885.                            option is not specified or there are less than 4
  2886.                            elements, then the default colors are used.  These
  2887.                            defaults are:
  2888.  
  2889.                               colors[1] = Standard color setting
  2890.                               colors[2] = Bright standard color 
  2891.                               colors[3] = Enhanced color setting
  2892.                               colors[4] = Blinking enhanced color
  2893.  
  2894.  
  2895.        Behavior:
  2896.  
  2897.             MARKREC() behaves very similar to PICKREC() except instead if
  2898.             picking one record, you mark several records for processing. 
  2899.             MARKREC() skips forward and backward through the database records
  2900.             as the up and down arrow keys are pressed.  The PgUp and PgDn
  2901.             scroll one window full of records.  When the Enter key is pressed,
  2902.             MARKREC() exits and returns a list of selected records in the form
  2903.             of a string of record numbers, each 8 digits with a comma
  2904.             delimiter.  For example, if the marked records were record numbers
  2905.             5, 12 and 123, the string would be: "       5,      12,     123,". 
  2906.             Notice the trailing comma, as a comma is added to the end of each
  2907.             selected record number.  To process the selected records you may
  2908.             use either FOR...$ logic, or a loop to extract each record number
  2909.             to process.  See the examples.  If the markfield parameter is
  2910.             supplied, this field (or expression) is extracted, and a trailing
  2911.             comma added to the end.  You can create your parsing loop based on
  2912.             the length of this field or expression.
  2913.  
  2914.             If the field list expression display is wider that the width of
  2915.             the display box, it is truncated; if it is shorter, spaces are
  2916.             added onto the end to make the selection bar as wide as the box.
  2917.  
  2918.  
  2919.        Examples:
  2920.  
  2921.             *-- database of customer orders, select orders to print
  2922.  
  2923.             *-- Orderno and Customer are fields in your database
  2924.             output = "Orderno + ' ' + Customer"
  2925.  
  2926.             *-- draw a double line box with a title header
  2927.             @ 1,0,22,36 BOX '        '
  2928.  
  2929.        _______________________________________________________________________
  2930.        RLIB 2.0                                                             50
  2931.  
  2932.  
  2933.             @ 2,0 SAY '           CUSTOMER ORDERS           '
  2934.             @ 3,0 SAY '                                     '
  2935.  
  2936.             marked = MARKREC( 4, 2, 21, 35, output, -4 )
  2937.  
  2938.             *-- now could print information in one of two ways
  2939.             *-- #1
  2940.             REPORT FORM custrepo FOR STR(RECNO(),8,0)+"," $ marked
  2941.             *-- the comma on the end solves the problem of a mistaken
  2942.             *-- match from two record numbers concatenated together
  2943.             *-- "       110000000" = record 1 and 10000000, but would
  2944.             *-- match on record number 11 or 110 or 1100 etc...
  2945.  
  2946.  
  2947.             *-- method number 2 is quicker but more code
  2948.             DO WHILE LEN(marked) > 0
  2949.                *-- get a record number from list (1st 8 digits in list)
  2950.                mrecord = VAL(SUBSTR(marked,1,8))
  2951.                GOTO mrecord
  2952.                DO <report printing routine>
  2953.                *-- strip off first 9 characters (8 digits plus a comma)
  2954.                marked = SUBSTR(marked,10)
  2955.             ENDDO
  2956.  
  2957.  
  2958.        Source:    RL_MARKR.PRG
  2959.  
  2960.  
  2961.        See also:  PICKREC()
  2962.  
  2963.  
  2964.  
  2965.  
  2966.  
  2967.  
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.  
  2974.  
  2975.  
  2976.  
  2977.  
  2978.  
  2979.  
  2980.  
  2981.  
  2982.  
  2983.  
  2984.  
  2985.  
  2986.  
  2987.  
  2988.        _______________________________________________________________________
  2989.        RLIB 2.0                                                             51
  2990.  
  2991.  
  2992.  
  2993.                                      MEMORIZE()
  2994.                                      ----------
  2995.  
  2996.  
  2997.  
  2998.        This function is designed to be used in conjunction with the CHANGED(),
  2999.        MREPLACE(), and FORGET() functions; they are all a team.  Put together,
  3000.        they simplify the 'scattering and gathering' of database field contents
  3001.        into and from associated memory variables (some languages call them
  3002.        temporary field variables).  What MEMORIZE() does is to create a PUBLIC
  3003.        memory variable with the same name as each of the fields in the current
  3004.        record of the currently selected database file, and assigns to that
  3005.        memory variable the value of its associated field.  You then GET the
  3006.        contents of the memory variable rather than GETting the field directly. 
  3007.        After your READ is finished, you check to see if any of the memory
  3008.        variable values have CHANGED() from their database field counterparts
  3009.        and, if so, issue a MREPLACE() then FORGET() them.  The process may
  3010.        seem a little complicated at first, but it's a lot easier than
  3011.        cluttering up code with STORE TO's and REPLACE WITH's.
  3012.  
  3013.  
  3014.        Syntax:
  3015.  
  3016.             MEMORIZE( [ blank ] )
  3017.  
  3018.  
  3019.        Returns:
  3020.  
  3021.             True (.T.) if all fields successively stored to memory variables.
  3022.  
  3023.  
  3024.        Parameters:
  3025.  
  3026.             blank......... Optional LOGICAL (.T.|.F.) which if given and is
  3027.                            True tells MEMORIZE() to create a empty M->memvar
  3028.                            of the associated field type for each database
  3029.                            record field.
  3030.  
  3031.  
  3032.        Usage:
  3033.  
  3034.             Used to store a working copy of all the database record field
  3035.             contents to memory variables for editing.  This is good
  3036.             programming practice in that you should never GET a field
  3037.             directly, but only work with a copy which can later be REPLACed. 
  3038.             The 'blank' option is useful for creating a set of field variables
  3039.             when appending a new record.  Remember, memory variables created
  3040.             with MEMORIZE() have the same name as their database field
  3041.             counterparts.  Whenever there are fields and memory variables with
  3042.             the same names, fields take precedence.  So to access these
  3043.             variables you must preface the variable name with the memory
  3044.             variable identifier alias M->.
  3045.  
  3046.  
  3047.        _______________________________________________________________________
  3048.        RLIB 2.0                                                             52
  3049.  
  3050.  
  3051.  
  3052.        Behavior:
  3053.  
  3054.             Each memory variable created is the same data type as its
  3055.             associated field.  If the optional blank parameter is supplied,
  3056.             each of these variables are empty (Memo field variables are
  3057.             initialized as a character string of zero length).  The following
  3058.             table of samples gives the data types created:
  3059.  
  3060.             FIELD NAME  FIELD TYPE  LENGTH   VARIABLE NAME  BLANK VALUE
  3061.             ----------  ----------  ------   -------------  ----------------
  3062.             Name        Character     32     M->name        SPACE(32)
  3063.             BirthDate   Date           8     M->birthdate   CTOD('  /  /  ')
  3064.             Age         Numeric        2     M->age         0
  3065.             Male        Logical        1     M->male        .F.
  3066.             Comments    Memo          10     M->comments    ''
  3067.  
  3068.  
  3069.        Example:
  3070.  
  3071.             *-- store empty field values for a new record
  3072.             MEMORIZE(.T.)
  3073.  
  3074.             *-- get the data
  3075.             @ 1,0 SAY 'Enter full name' GET M->name
  3076.             @ 2,0 SAY 'Enter birthdate' GET M->birthdate
  3077.             @ 3,0 SAY 'Enter age      ' GET M->age PICTURE '##'
  3078.             *-- remember to always PICTURE numeric memory variables
  3079.             READ
  3080.  
  3081.             *-- now add the new record and put in the data
  3082.             APPEND BLANK
  3083.             MREPLACE()
  3084.  
  3085.             *-- now release the public variables
  3086.             FORGET()
  3087.  
  3088.  
  3089.        Source:    RL_MEMOR.PRG
  3090.  
  3091.  
  3092.        See also:  CHANGED(), MREPLACE(), FORGET()
  3093.  
  3094.  
  3095.  
  3096.  
  3097.  
  3098.  
  3099.  
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.  
  3106.        _______________________________________________________________________
  3107.        RLIB 2.0                                                             53
  3108.  
  3109.  
  3110.  
  3111.                                      MREPLACE()
  3112.                                      ----------
  3113.  
  3114.  
  3115.  
  3116.        This functions is designed to be used in conjunction with MEMORIZE(),
  3117.        CHANGED(), and FORGET() functions; they are all a team.  Put together,
  3118.        they simplify the 'scattering and gathering' of database field contents
  3119.        into and from associated memory variables (some languages call them
  3120.        temporary field variables).  What MREPLACE() does is to replace each
  3121.        field in the current database record with the associated field memory
  3122.        variable that was created with MEMORIZE() and, usually, recently
  3123.        edited.
  3124.  
  3125.  
  3126.        Syntax:
  3127.  
  3128.             MREPLACE()
  3129.  
  3130.  
  3131.        Returns:
  3132.  
  3133.             True (.T.) if all fields successively replace.
  3134.  
  3135.  
  3136.        Parameters:
  3137.  
  3138.             None.
  3139.  
  3140.  
  3141.        Behavior:
  3142.  
  3143.             Memory variables created with MEMORIZE() have the same name as
  3144.             their database field counterparts.  Whenever there are fields and
  3145.             memory variables with the same names, fields take precedence.  So
  3146.             to access these variables you must preface the variable/field name
  3147.             with the memory variable identifier alias M->.  MREPLACE() does a
  3148.             REPLACE <field> WITH <fieldvar> for each field of the database
  3149.             record.
  3150.  
  3151.  
  3152.        Example:
  3153.  
  3154.             *-- store field values
  3155.             MEMORIZE()
  3156.  
  3157.             *-- get the data
  3158.             @ 1,0 SAY 'Enter full name' GET M->name
  3159.             @ 2,0 SAY 'Enter city name' GET M->city
  3160.             @ 3,0 SAY 'Enter the State' GET M->state
  3161.             @ 4,0 SAY 'Enter the zip  ' GET M->zip
  3162.             READ
  3163.  
  3164.  
  3165.        _______________________________________________________________________
  3166.        RLIB 2.0                                                             54
  3167.  
  3168.  
  3169.             *-- if changed, update the record, otherwise why bother
  3170.             IF CHANGED()
  3171.                IF .NOT. MREPLACE()
  3172.                   SAYINBOX('Error writing fields!  Replace failed.')
  3173.                ENDIF
  3174.             ENDIF
  3175.  
  3176.             *-- now release the public variables
  3177.             FORGET()
  3178.  
  3179.  
  3180.        Source:    RL_MREPL.PRG
  3181.  
  3182.  
  3183.        See also:  CHANGED(), FORGET(), MEMORIZE()
  3184.  
  3185.  
  3186.  
  3187.  
  3188.  
  3189.  
  3190.  
  3191.  
  3192.  
  3193.  
  3194.  
  3195.  
  3196.  
  3197.  
  3198.  
  3199.  
  3200.  
  3201.  
  3202.  
  3203.  
  3204.  
  3205.  
  3206.  
  3207.  
  3208.  
  3209.  
  3210.  
  3211.  
  3212.  
  3213.  
  3214.  
  3215.  
  3216.  
  3217.  
  3218.  
  3219.  
  3220.  
  3221.  
  3222.  
  3223.  
  3224.        _______________________________________________________________________
  3225.        RLIB 2.0                                                             55
  3226.  
  3227.  
  3228.  
  3229.                                      MULTIMENU()
  3230.                                      -----------
  3231.  
  3232.  
  3233.                   
  3234.        MULTIMENU is a Multi-column menu selection function.  Many programs
  3235.        offer a list of options to choose from displayed across the screen,
  3236.        allowing you to cursor up, down, left and right to navigate around the
  3237.        options.  This function takes an array of character strings and
  3238.        displays them in this format.
  3239.  
  3240.  
  3241.        Syntax:
  3242.  
  3243.             MULTIMENU( top, left, bottom, right, options [, columns ;
  3244.                        [, messages [, message_row [, colors ] ] ] ] )
  3245.  
  3246.  
  3247.        Returns:
  3248.  
  3249.             The number of the array element chosen, or zero if the escape key
  3250.             is pressed.
  3251.  
  3252.  
  3253.        Parameters:
  3254.  
  3255.             top..........  Numeric values specifying the window coordinates
  3256.             left.........  of the 'display box'.  The top and bottom values
  3257.             bottom.......  must be between 0 and 24, and the left and right
  3258.             right........  coordinates must be between 0 and 79.
  3259.  
  3260.             options......  Array of options.  Specify the array name without
  3261.                            quotes to pass this array by reference.
  3262.  
  3263.             columns......  Optional numeric value indicating the number of
  3264.                            columns to use for displaying the options.  If this
  3265.                            parameter is omitted, or a non numeric data type is
  3266.                            passed, or if it is zero, the columns will be
  3267.                            calculated to fit the most options across the
  3268.                            'window' boundaries.
  3269.  
  3270.             messages.....  Optional array of messages corresponding to each of
  3271.                            the options.  Specify the array name without quotes
  3272.                            to pass the array by reference.
  3273.  
  3274.             message_row..  Optional numeric value indicating the row for the
  3275.                            optional messages to appear.  This value must be
  3276.                            between 0 and 24.  The default is row 24.
  3277.  
  3278.             colors.......  Optional array of character strings specifying the
  3279.                            color settings to use.  The colors used for the
  3280.                            different parts of the menu are specified as
  3281.                            follows:
  3282.  
  3283.        _______________________________________________________________________
  3284.        RLIB 2.0                                                             56
  3285.  
  3286.  
  3287.  
  3288.                               colors[1] =  Menu choices.
  3289.                               colors[2] =  Menu selection bar.
  3290.                               colors[3] =  <not used>
  3291.                               colors[4] =  <not used>
  3292.                               colors[5] =  Selected choice on exit.
  3293.  
  3294.                            If you use this color feature, DECLARE your colors
  3295.                            array to have at least 5 elements.  If the colors
  3296.                            option is not specified or there are less than 5
  3297.                            elements, then the default colors are used.  These
  3298.                            defaults are: the current Standard color is used
  3299.                            for the item displays, and the Enhanced color is
  3300.                            used for the menu selection bar.
  3301.  
  3302.  
  3303.        Behavior:
  3304.  
  3305.             If any of the first four parameters specifying the window
  3306.             coordinates are out of bounds, or the <right> is less than or
  3307.             equal to <left>, or <bottom> is less than or equal to <top>,
  3308.             MULTIMENU will bomb out and return zero.  Also, if the options
  3309.             array is empty, a zero will be returned.  If the number of columns
  3310.             option is omitted (or zero to make the number of columns
  3311.             automatic), MULTIMENU will position columns so that columns are
  3312.             separated by at least one space.  If more elements exist in the
  3313.             array than will fit in the display window given the number of
  3314.             columns being used, the PgDn and PgUp keys will skip forward and
  3315.             back between windows.
  3316.  
  3317.  
  3318.        Example:
  3319.  
  3320.             *-- display fields in box with structure for each shown below
  3321.             USE manyflds.dbf
  3322.  
  3323.             *-- declare arrays for field names
  3324.             num = FCOUNT()
  3325.             DECLARE fields[num], types[num], widths[num], dec[num]
  3326.             DECLARE struct[num]
  3327.  
  3328.             AFIELDS( fields, types, widths, dec )  && fill with .DBF info
  3329.  
  3330.             FOR x = 1 TO num
  3331.                *-- now make each field name 12 spaces wide
  3332.                fields[x] = STRETCH(fields[x],12)
  3333.                *-- and build field description for each
  3334.                struct[x] = IF( types[x] = 'C', 'Character',;
  3335.                            IF( types[x] = 'N', 'Numeric',;
  3336.                            IF( types[x] = 'L', 'Logical',;
  3337.                            IF( types[x] = 'D', 'Date', 'Memo')))) +;
  3338.                            '  Length: '   + STR(widths[x],3,0) +;
  3339.                            '  Decimals: ' + STR(dec[x],3,0)
  3340.             NEXT x
  3341.  
  3342.        _______________________________________________________________________
  3343.        RLIB 2.0                                                             57
  3344.  
  3345.  
  3346.  
  3347.             *-- now present these fields in a single line box
  3348.             @ 1,0,10,79 BOX '        '
  3349.  
  3350.             *-- present fields with structure for each on line 11
  3351.             *-- the zero makes UDF calc column number dynamically
  3352.             fieldnum = MULTIMENU( 2,1,9,78, fields, 0, struct, 11 )
  3353.  
  3354.  
  3355.        Source:    RL_MULTI.PRG
  3356.  
  3357.  
  3358.        See also:  BARMENU(), BOXMENU()
  3359.  
  3360.  
  3361.  
  3362.  
  3363.  
  3364.  
  3365.  
  3366.  
  3367.  
  3368.  
  3369.  
  3370.  
  3371.  
  3372.  
  3373.  
  3374.  
  3375.  
  3376.  
  3377.  
  3378.  
  3379.  
  3380.  
  3381.  
  3382.  
  3383.  
  3384.  
  3385.  
  3386.  
  3387.  
  3388.  
  3389.  
  3390.  
  3391.  
  3392.  
  3393.  
  3394.  
  3395.  
  3396.  
  3397.  
  3398.  
  3399.  
  3400.  
  3401.        _______________________________________________________________________
  3402.        RLIB 2.0                                                             58
  3403.  
  3404.  
  3405.  
  3406.                                      NAMESPLIT()
  3407.                                      -----------
  3408.  
  3409.  
  3410.  
  3411.        This function is useful for parsing names to split up into the lastname
  3412.        firstname components.  What NAMESPLIT does is let you type in a name in
  3413.        the form RICHARD LOW, and it returns LOW, RICHARD.  This is
  3414.        particularly useful for SEEKing names from an index that was indexed on
  3415.        PAD(TRIM(Lastname) + ', ' + Firstname, 32).  Such an index will insure
  3416.        correct ordering of names.
  3417.  
  3418.  
  3419.        Syntax:
  3420.  
  3421.             NAMESPLIT( name )
  3422.  
  3423.  
  3424.        Returns:
  3425.  
  3426.             A character string equal to name flipped to Lastname first, with a
  3427.             comma space inserted.
  3428.  
  3429.  
  3430.        Parameters:
  3431.  
  3432.             name.........  Character string indicating the string to parse
  3433.                            into Lastname, Firstname.
  3434.  
  3435.  
  3436.        Behavior:
  3437.  
  3438.             NAMESPLIT is aware of the standard name suffixes, i.e. JR. SR. II,
  3439.             2ND, III, 3RD, 4TH, M.D., PHD, and will make recognize these as
  3440.             not being lastnames.  Without this, a name entered as RICHARD C.
  3441.             LOW, JR. may incorrectly be split into JR., RICHARD C
  3442.  
  3443.  
  3444.        Example:
  3445.  
  3446.             *-- file is indexed on: PAD( TRIM(Lastname)+", "+Firstname, 32 )
  3447.  
  3448.             ACCEPT 'Enter name to locate:' TO mname
  3449.             *-- they enter "RICHARD LOW"
  3450.  
  3451.             SEEK NAMESPLIT(mname)
  3452.             *-- it finds "LOW, RICHARD"
  3453.  
  3454.  
  3455.        Source:    RL_NAMES.PRG
  3456.  
  3457.  
  3458.        See also:  KEYINPUT()
  3459.  
  3460.        _______________________________________________________________________
  3461.        RLIB 2.0                                                             59
  3462.  
  3463.  
  3464.  
  3465.                                      NTXKEYVAL()
  3466.                                      -----------
  3467.  
  3468.  
  3469.  
  3470.        This function allows you to easily get the value of an index key field
  3471.        from the currently selected database.  It is handy in place of using
  3472.        the INDEXKEY() function and subsequent macro substitution.
  3473.  
  3474.  
  3475.        Syntax:
  3476.  
  3477.             NTXKEYVAL()
  3478.  
  3479.  
  3480.        Returns:
  3481.  
  3482.             The value of the current database index key, of a type determined
  3483.             by the type of field in the index key expression.
  3484.  
  3485.  
  3486.        Parameters:
  3487.  
  3488.             None.
  3489.  
  3490.  
  3491.        Behavior:
  3492.  
  3493.             If no database file is open, or no index file is open, NTXKEYVAL()
  3494.             returns a null string ("").
  3495.  
  3496.  
  3497.        Example:
  3498.  
  3499.             *-- save the index key value for comparison
  3500.             savekey = NTXKEYVAL()
  3501.  
  3502.             *-- do whatever you want to do
  3503.             .
  3504.             .
  3505.  
  3506.             *-- see if an index key field was changed in the process
  3507.             IF savekey != NTXKEYVAL()
  3508.                *-- do corrective things
  3509.             ENDIF
  3510.  
  3511.  
  3512.        Source:    RL_NTXKE.PRG
  3513.  
  3514.  
  3515.        See also:  PICKREC()
  3516.  
  3517.  
  3518.  
  3519.        _______________________________________________________________________
  3520.        RLIB 2.0                                                             60
  3521.  
  3522.  
  3523.  
  3524.                                       PARENT()
  3525.                                       --------
  3526.  
  3527.  
  3528.  
  3529.        This function returns the name of the parent directory to either the
  3530.        current directory, or to the optionally supplied directory.
  3531.  
  3532.  
  3533.        Syntax:
  3534.  
  3535.             PARENT( [directory] )
  3536.  
  3537.  
  3538.        Returns:
  3539.  
  3540.             A character string indicating the name of the parent directory
  3541.             (i.e. the directory above).
  3542.  
  3543.  
  3544.        Parameters:
  3545.  
  3546.             directory..... Optional name of the directory whose parent
  3547.                            directory you wish to find.
  3548.  
  3549.  
  3550.        Usage:
  3551.  
  3552.             This can be useful in directory/file management routines when you
  3553.             want to let a user navigate through the directory structure. 
  3554.             Although you can get the names of sub-directories with ADIR(), if
  3555.             you want to take them 'back up' a directory, you have to get the
  3556.             current directory name, and strip it down to find the parent
  3557.             directory part.  PARENT() makes this task easy.
  3558.  
  3559.  
  3560.        Behavior:
  3561.  
  3562.             If the current or supplied directory is at the top level (i.e. the
  3563.             root directory), PARENT() will return '\'.
  3564.  
  3565.  
  3566.        Example:
  3567.  
  3568.             *-- current directory is \APPS\CLIPPER\TEST
  3569.             ? PARENT()                          && returns '\APPS\CLIPPER'
  3570.             ? PARENT('C:\DOS\UTILITY')          && returns 'C:\DOS'
  3571.  
  3572.  
  3573.        Source:    RL_PAREN.PRG
  3574.  
  3575.  
  3576.        See also:  PATHTO()
  3577.  
  3578.        _______________________________________________________________________
  3579.        RLIB 2.0                                                             61
  3580.  
  3581.  
  3582.  
  3583.                                       PATHTO()
  3584.                                       --------
  3585.  
  3586.  
  3587.  
  3588.        This function searches the current DOS path to find the path pointing
  3589.        to the indicated file.  This is usually used to build a fully qualified
  3590.        filename ('d:[path]filename') as a character string to be used to open
  3591.        a file.  In the example below, a help file is kept in the same drive
  3592.        and directory as the program (.EXE) file.  The path to the .EXE file is
  3593.        found and used to point to the help file.  This way, the help file can
  3594.        be located at runtime, provided the directory it is in is in the path.
  3595.  
  3596.  
  3597.        Syntax:
  3598.  
  3599.             PATHTO( filename )
  3600.  
  3601.  
  3602.        Returns:
  3603.  
  3604.             A character string indicating the path pointing to <filename> plus
  3605.             a trailing backslash '\'.  If the file is not found along the DOS
  3606.             path, then a null string ('') is returned.
  3607.  
  3608.  
  3609.        Parameters:
  3610.  
  3611.             filename.....  The name of the file to find through the path.
  3612.  
  3613.  
  3614.        Example:
  3615.  
  3616.             *-- Example program name is DEMO.EXE, and help file is named
  3617.             *-- DEMO.HLP and both are located in C:\MYAPPS.
  3618.             *-- path=C:\;C:\DOS;C:\CLIPPER;C:\UTILITY;C:\MYAPPS 
  3619.  
  3620.             PROCEDURE Help
  3621.             PARAMETERS a,b,c                       && remember to get parms
  3622.             helppath = PATHTO('demo.exe')          && returns 'C:\MYAPPS\'
  3623.             helpfile = helppath + 'DEMO.HLP'       && 'C:\MYAPPS\DEMO.HLP'
  3624.  
  3625.             IF FILE(helpfile)
  3626.                USE &helpfile
  3627.                <help code>
  3628.             ENDIF
  3629.             RETURN
  3630.  
  3631.  
  3632.        Source:    RL_PATHT.PRG
  3633.  
  3634.  
  3635.        See also:  PARENT()
  3636.  
  3637.        _______________________________________________________________________
  3638.        RLIB 2.0                                                             62
  3639.  
  3640.  
  3641.  
  3642.                                      PDOWNINIT()
  3643.                                      -----------
  3644.  
  3645.  
  3646.  
  3647.        To initialize the PDOWNMENU() function.  This call is required to set
  3648.        up the variables used to control PDOWNMENU().  Since PDOWNMENU() has a
  3649.        lot of work to do, it is inefficient to repeat many of the processes
  3650.        each time the function is called.  Therefore, I split it up into an
  3651.        initialization routine, and the menuing routine.
  3652.  
  3653.  
  3654.        Syntax:
  3655.  
  3656.             PDOWNINIT( [ row, columns, menus, items, startnums [,prompts ;
  3657.                         [,promptrow [,colors [,altkeys [,exit ]]]]] ] )
  3658.  
  3659.  
  3660.        Returns:
  3661.  
  3662.             True if initialization was successful, false otherwise.
  3663.  
  3664.  
  3665.        Parameters:
  3666.  
  3667.             row........... Numeric value indicating the row for the pull down
  3668.                            menus to appear.  Value must be between 0 and 24.
  3669.  
  3670.             columns....... Array of column numbers indicating the left corner
  3671.                            position for each of the pull down menus.  The
  3672.                            column numbers must be between 0 and 79, and the
  3673.                            left column of a given menu must be less than 79 -
  3674.                            the width of the menu, or erratic screen painting
  3675.                            errors will occur.
  3676.  
  3677.             menus......... Array of top level menu choices.  These are the
  3678.                            menu options that appear across the top (on row) in
  3679.                            a manner similar to BARMENU().
  3680.  
  3681.             items......... Array of pull down menu items.  There must be at
  3682.                            least one element for each option of each menu. 
  3683.                            These are the options that 'fill' each of the pull-
  3684.                            down boxed menus.
  3685.  
  3686.             startnums..... Array element numbers indicating at which element
  3687.                            number each set of menu options start within the
  3688.                            items array.  There should be one element for each
  3689.                            corresponding menu.
  3690.  
  3691.             prompts....... Optional array of messages which correspond to each
  3692.                            of the menu items.  There should be one element for
  3693.                            each corresponding item.
  3694.  
  3695.  
  3696.        _______________________________________________________________________
  3697.        RLIB 2.0                                                             63
  3698.  
  3699.  
  3700.             promptrow..... Optional numeric row on which these prompts will
  3701.                            appear.
  3702.  
  3703.             colors........ Optional ARRAY of colors to use for the top Bar and
  3704.                            pull down Box menus.
  3705.  
  3706.                               color[1] - Option & message displays
  3707.                               color[2] - Menu selection bars
  3708.                               color[3] - Pull-down menu box ACTIVE color
  3709.                               color[4] - Pull-down menu box IN-ACTIVE color
  3710.                               color[5] - Pull-down menu option after selection
  3711.                               color[6] - Menu bar option after selection
  3712.  
  3713.                            If omitted, the default colors for the menus are:
  3714.  
  3715.                               color[1] - Current Standard color.
  3716.                               color[2] - Current Enhanced color.
  3717.                               color[3] - Bright (BRIGHT()) Standard color.
  3718.                               color[4] - Current Standard color.
  3719.                               color[5] - Bright (BRIGHT()) Standard color.
  3720.                               color[6] - Bright (BRIGHT()) Standard color.
  3721.  
  3722.             altkeys....... Optional array of character strings indicating the
  3723.                            alternate select keys for each of the pull-down
  3724.                            menu choices.  There should be one element for each
  3725.                            corresponding menu.  If omitted, the default direct
  3726.                            select keys is the first letter of each menu item.
  3727.  
  3728.             exit.......... Optional logical value indicating if the ESCAPE key
  3729.                            will cause an exit from the top level menu.  If
  3730.                            omitted, the default is false.
  3731.  
  3732.  
  3733.        Usage:
  3734.  
  3735.             PDOWNINIT() establishes the working environment for PDOWNMENU(),
  3736.             things such as the column coordinates, underlying screen, menu
  3737.             colors, alternate select keys etc..  If this information had to be
  3738.             re-passed to PDOWNMENU() on each call (many times in a menu
  3739.             control loop) then the parameter passing and parameter parsing
  3740.             overhead would slow PDOWNMENU() unnecessarily.
  3741.  
  3742.  
  3743.        Behavior:
  3744.  
  3745.             Upon initialization, a PUBLIC array is established to hold various
  3746.             environment information.  This array is named RL_PD[], so check
  3747.             that this name does not conflict with any others in your program. 
  3748.             To release this public array, and clear the PDOWNMENU environment,
  3749.             issue the PDOWNINIT() function with no parameters.  Although not
  3750.             absolutely necessary, it is probably a good idea to release
  3751.             variables and arrays that are not being used.
  3752.  
  3753.  
  3754.  
  3755.        _______________________________________________________________________
  3756.        RLIB 2.0                                                             64
  3757.  
  3758.  
  3759.        Examples:
  3760.  
  3761.             *-- arrays to hold top menu, columns, and starting elements
  3762.             DECLARE menus[5], columns[5], starts[5]
  3763.  
  3764.             menus[1] = 'File'
  3765.             menus[2] = 'Edit'
  3766.             menus[3] = 'View'
  3767.             menus[4] = 'Utility'
  3768.             menus[5] = 'Quit'
  3769.  
  3770.             columns[1] =  0
  3771.             columns[2] = 24
  3772.             columns[3] = 41
  3773.             columns[4] = 58
  3774.             columns[5] = 76
  3775.  
  3776.             *-- declare array to hold items in each menu
  3777.             DECLARE items[14]
  3778.  
  3779.             starts[1] = 1
  3780.             items[ 1] = 'Retrieve '
  3781.             items[ 2] = 'Save     '
  3782.             items[ 3] = 'Erase    '
  3783.  
  3784.             starts[2] = 4
  3785.             items[ 4] = 'Record '
  3786.             items[ 5] = 'File   '
  3787.             items[ 6] = 'Memo   '
  3788.  
  3789.             starts[3] = 7
  3790.             items[ 7] = 'Record '
  3791.             items[ 8] = 'File   '
  3792.             items[ 9] = 'Memo   '
  3793.  
  3794.             starts[4] = 10
  3795.             items[10] = 'Directory '
  3796.             items[11] = 'Reccount  '
  3797.             items[12] = 'Index     '
  3798.  
  3799.             starts[5] = 13
  3800.             items[13] = 'No  '
  3801.             items[14] = 'Yes '
  3802.  
  3803.  
  3804.             *-- initialize Pull Down menu on row 1 using default colors & keys
  3805.             CLEAR
  3806.             PDOWNINIT( 1, columns, menus, items, starts )
  3807.  
  3808.  
  3809.        Source:    RL_PDOWN.PRG
  3810.  
  3811.  
  3812.        See also:  BARMENU(), BOXMENU(), MULTIMENU(), PDOWNMENU()
  3813.  
  3814.        _______________________________________________________________________
  3815.        RLIB 2.0                                                             65
  3816.  
  3817.  
  3818.  
  3819.                                      PDOWNMENU()
  3820.                                      -----------
  3821.  
  3822.  
  3823.  
  3824.        To perform the pull down menuing function after having been initialized
  3825.        with the PDOWNINIT() function.
  3826.  
  3827.  
  3828.        Syntax:
  3829.  
  3830.             PDOWNMENU( @menu, @item, menus, items, columns, startnums;
  3831.                         [, prompts [, exit ] ] ) 
  3832.  
  3833.  
  3834.        Returns:
  3835.  
  3836.             A numeric value equal to the item selected (from the items array)
  3837.             or zero if escaped pressed (and allowed).  Also, since <menu> and
  3838.             <item> are passed by reference, <menu> will equal the
  3839.             corresponding menu number, and <item> the item number as it
  3840.             appears in the menu, starting at 1.
  3841.  
  3842.  
  3843.        Parameters:
  3844.  
  3845.             @menu......... This must be a numeric variable which is passed by
  3846.                            reference by preceding it with the '@' symbol. 
  3847.                            This allows PDOWNMENU() to change the value of this
  3848.                            variable so your program can act on its value.
  3849.  
  3850.             @item......... As with @menu, this must be a numeric variable
  3851.                            which is passed by reference by preceding it with
  3852.                            the '@' symbol.  This allows PDOWNMENU() to change
  3853.                            the value of this variable so your program can act
  3854.                            on its value.
  3855.  
  3856.             menus......... Array of top level menu choices.
  3857.  
  3858.             items......... Array of pull down menu items.  There must be one
  3859.                            element for each option of each menu.
  3860.  
  3861.             columns....... Array of column numbers indicating the left corner
  3862.                            position for each of the pull down menus.  The
  3863.                            column numbers must be between 0 and 79, and the
  3864.                            left column of a given menu must be less than 79 -
  3865.                            the width of the menu, or erratic screen painting
  3866.                            errors will occur.
  3867.  
  3868.             startnums..... Array element numbers indicating at which element
  3869.                            number each set of menu options start within the
  3870.                            items array.
  3871.  
  3872.  
  3873.        _______________________________________________________________________
  3874.        RLIB 2.0                                                             66
  3875.  
  3876.  
  3877.             prompts....... Optional array of messages which correspond to each
  3878.                            of the menu items.  There should be one element for
  3879.                            each corresponding item.
  3880.  
  3881.             exit.......... Optional logical value indicating if the ESCAPE key
  3882.                            will cause an exit from the top level menu.  If
  3883.                            omitted, the default is false.
  3884.  
  3885.  
  3886.        Usage:
  3887.  
  3888.             Used to create 'pull down' menus seen in so many applications
  3889.             these days.
  3890.  
  3891.  
  3892.        Behavior:
  3893.  
  3894.             The pull down menu consists of two parts: the 'top' level menu
  3895.             which looks and acts like BARMENU(), and the 'pulled down' menus,
  3896.             which look and act like BOXMENU()s.  When the menu starts, the
  3897.             left and right arrow keys move the selection bar across the top
  3898.             menu selection the different menu options.  When either the ENTER
  3899.             key, or the first letter of one of the menu selections is pressed,
  3900.             the menu drops down to the pull down menu.  At this point, the up
  3901.             and down arrow keys highlite the different menu options, and the
  3902.             ENTER key or first letter selects each one.  The left and right
  3903.             arrow keys at this point cause PDOWNMENU() to skip from pull down
  3904.             menu to pull down menu.
  3905.  
  3906.  
  3907.        Examples:
  3908.  
  3909.             *-- after having been initialized (see above), do the menu
  3910.             menu   = 1                          && start on menu number 1
  3911.             choice = 0                          && do not "pull down" on entry
  3912.  
  3913.             DO WHILE menu < 5                   && #5 = Quit
  3914.  
  3915.                PDOWNMENU( @menu, @choice, menus, items, columns, starts )
  3916.  
  3917.                DO CASE
  3918.                   CASE menu = 1                 && File
  3919.                      DO fileproc WITH choice
  3920.                   CASE menu = 2                 && Edit
  3921.                      DO editproc WITH choice
  3922.                   CASE menu = 3                 && View
  3923.                      DO viewproc WITH choice
  3924.                   CASE menu = 4                 && Utility
  3925.                      DO utilproc WITH choice
  3926.                ENDCASE
  3927.             ENDDO
  3928.             RETURN
  3929.  
  3930.  
  3931.  
  3932.        _______________________________________________________________________
  3933.        RLIB 2.0                                                             67
  3934.  
  3935.  
  3936.             PROCEDURE fileproc
  3937.             PARAMETER choice
  3938.  
  3939.             DO CASE
  3940.                CASE choice = 1
  3941.                   DO retrieve
  3942.                CASE choice = 2
  3943.                   DO save
  3944.                CASE choice = 3
  3945.                   DO erase
  3946.             ENDCASE
  3947.             RETURN
  3948.  
  3949.  
  3950.        Source:    RL_PDOWN.PRG
  3951.  
  3952.  
  3953.        See also:  BARMENU(), BOXMENU(), MULTIMENU()
  3954.  
  3955.  
  3956.  
  3957.  
  3958.  
  3959.  
  3960.  
  3961.  
  3962.  
  3963.  
  3964.  
  3965.  
  3966.  
  3967.  
  3968.  
  3969.  
  3970.  
  3971.  
  3972.  
  3973.  
  3974.  
  3975.  
  3976.  
  3977.  
  3978.  
  3979.  
  3980.  
  3981.  
  3982.  
  3983.  
  3984.  
  3985.  
  3986.  
  3987.  
  3988.  
  3989.  
  3990.  
  3991.        _______________________________________________________________________
  3992.        RLIB 2.0                                                             68
  3993.  
  3994.  
  3995.  
  3996.                                      PICKFILE()
  3997.                                      ----------
  3998.  
  3999.  
  4000.  
  4001.        To display a boxed file directory listing from which to choose a file. 
  4002.        This functions allows you to easily build pop-up file listings when you
  4003.        need to prompt a user for a filename.
  4004.  
  4005.  
  4006.        Syntax:
  4007.  
  4008.             PICKFILE( [ filespec [, top, left, bottom [, colors;
  4009.                       [, expanded ] ] ] ] )
  4010.  
  4011.  
  4012.        Returns:
  4013.  
  4014.             The selected filename as a character string, or a null string ('')
  4015.             if the Escape key is pressed.
  4016.  
  4017.  
  4018.        Parameters:
  4019.  
  4020.             filespec...... Optional filespec to use for the directory search. 
  4021.                            This filespec must follow the conventions required
  4022.                            by ADIR().  If omitted, PICKFILE() defaults to all
  4023.                            files (*.*).
  4024.  
  4025.             top........... Optional numeric value indicating the top row for
  4026.                            the directory box.  If omitted or an invalid
  4027.                            (dummy) parameter is specified, the default row is
  4028.                            row number 6, to center the box on the screen.  If
  4029.                            these coordinate parameters are used, all three
  4030.                            must be specified, otherwise the defaults take
  4031.                            hold.
  4032.  
  4033.             left.......... Optional numeric value indicating the left column
  4034.                            for the directory box.  If omitted or an invalid
  4035.                            (dummy) parameter is specified, the default is the
  4036.                            column position necessary to center the directory
  4037.                            box on the screen.
  4038.  
  4039.             bottom........ Numeric value indicating the bottom row for the
  4040.                            directory box.  If omitted or an invalid (dummy)
  4041.                            parameter is specified, the default row is row
  4042.                            number 19, to center the box on the screen.
  4043.  
  4044.             colors........ Optional character string specifying the color
  4045.                            settings to use.  This color setting is passed to
  4046.                            ACHOICE() so the format is that required by
  4047.                            ACHOICE().
  4048.  
  4049.  
  4050.        _______________________________________________________________________
  4051.        RLIB 2.0                                                             69
  4052.  
  4053.  
  4054.             expanded...... Optional logical (true|false) value indicating if
  4055.                            the file listing display is expanded to include
  4056.                            file size, date, and time.  The default is true.
  4057.  
  4058.  
  4059.        Usage:
  4060.  
  4061.             Useful for popping up file selection menus when a user is required
  4062.             to enter a filename for a file that already exists on disk.
  4063.  
  4064.  
  4065.        Behavior:
  4066.  
  4067.             After the file selection is made, the menu box disappears and the
  4068.             screen below it is restored.  As with all RLIB functions (except
  4069.             where noted) if you want to skip a parameter, you must pass a
  4070.             'dummy' parameter in the place of the one you want to skip.  The
  4071.             best dummy parameter is a null string ('').
  4072.  
  4073.  
  4074.        Example:
  4075.  
  4076.             *-- ask user for name of .DBF file to USE
  4077.  
  4078.             *-- make the F10 key the pop-up controller
  4079.             SET KEY -9 TO FileLister
  4080.  
  4081.             *-- allocate plenty of space for fully qualified filename
  4082.             dbf_file = SPACE(60)
  4083.             @ 10,0 SAY 'Enter filename or press F10 for a list';
  4084.                    GET dbf_file PICTURE '@!S40'
  4085.             READ
  4086.  
  4087.             *-- strip off the '.DBF' extension
  4088.             dbf_file = SUBSTR( dbf_file, 1, AT('.',dbf_file)-1 )
  4089.  
  4090.             USE &dbf_file
  4091.  
  4092.             <now do whatever>
  4093.  
  4094.  
  4095.             * Procedure: FileLister
  4096.             * Notes....: Procedure to pop-up list of .DBF files.  Remember
  4097.             *            to declare parameters in all SET KEY TO procedures.
  4098.             PROCEDURE FileLister
  4099.             PARAMETERS callproc, callline, inputvar
  4100.             &inputvar = PAD( PICKFILE('*.DBF'), LEN(&inputvar) )
  4101.             RETURN
  4102.  
  4103.  
  4104.        Source:    RL_PICKF.PRG
  4105.  
  4106.  
  4107.        See also:  BOXMENU(), PARENT(), PICKREC()
  4108.  
  4109.        _______________________________________________________________________
  4110.        RLIB 2.0                                                             70
  4111.  
  4112.  
  4113.  
  4114.                                       PICKREC()
  4115.                                       ---------
  4116.  
  4117.  
  4118.  
  4119.        This function provides an easy method of PICKing a RECord from the
  4120.        currently selected database.  One of the most functional uses is for
  4121.        producing pop-up listings in windows for on line help, or for supplying
  4122.        a menu of database records from which to select for editing, appending
  4123.        or deleting.  You simply give the function the four screen coordinates
  4124.        defining the 'display box', and the field list or expression to
  4125.        display, and it lists these expressions in a box for you to cursor up
  4126.        and down through to find the one you want and select it by pressing
  4127.        ENTER.  Other parameters allow you to call a procedure to perform
  4128.        display duties each time the arrow keys are pressed, and facilities for
  4129.        controlling the display refresh.
  4130.  
  4131.  
  4132.        Syntax:
  4133.  
  4134.             PICKREC( top, left, bottom, right, fieldlist, [, procname;
  4135.                      [, condition [, rownumber ] ] ] )
  4136.  
  4137.  
  4138.        Returns:
  4139.  
  4140.             Numeric value indicating the current row number (relative to the
  4141.             top of the 'display box') or zero if the Escape Key was pressed. 
  4142.             This return value is used in loops so that, upon return, PICKREC
  4143.             will know where it left off.  See the description of the
  4144.             row_number parameter and the example.
  4145.  
  4146.  
  4147.        Parameters:
  4148.  
  4149.             top........... Numeric values specifying the window coordinates
  4150.             left.......... of the 'display box'.  The top and bottom values
  4151.             bottom........ must be between 0 and 24, and the left and right
  4152.             right......... coordinates must be between 0 and 79.
  4153.  
  4154.             fieldlist..... Character expression which evaluates to a field
  4155.                            list to be displayed at runtime.  This value is
  4156.                            used as a macro substitution, so it must evaluate
  4157.                            correctly to a character string.  (Any valid
  4158.                            expression may be used.)
  4159.  
  4160.             procname...... Optional character string indicating the name of
  4161.                            the procedure to call after each keypress.  Care
  4162.                            must be taken to declare this procedure as EXTERNAL
  4163.                            unless you compile and link it in separately as it
  4164.                            is called via macro substitution.  If this
  4165.                            parameter is to be skipped, you must pass a 'dummy'
  4166.                            parameter, usually a null string.
  4167.  
  4168.        _______________________________________________________________________
  4169.        RLIB 2.0                                                             71
  4170.  
  4171.  
  4172.  
  4173.             condition..... Optional character string indicating the condition
  4174.                            that records must meet to be included in the list. 
  4175.                            This character string is evaluated at runtime via
  4176.                            macro substitution, therefore it MUST evaluate to a
  4177.                            logical expression!
  4178.  
  4179.             rownumber..... Numeric value indicating the current row number of
  4180.                            the 'selection bar' relative to the top of the
  4181.                            display box.  This parameter is required to allow
  4182.                            the function to 'remember' where the bar was upon
  4183.                            return from a previous selection.  Additionally,
  4184.                            this parameter allows display refresh control by
  4185.                            optionally passing the following values:
  4186.  
  4187.                               0  -  Clear display box, GO to TOP of the
  4188.                                     selected database or to the first record
  4189.                                     meeting <condition> if specified, and
  4190.                                     display records until box filled, End Of
  4191.                                     File, or <condition> is false.  Zero is
  4192.                                     the value passed at startup.
  4193.  
  4194.                              -1  -  Clear display box, display records
  4195.                                     starting at the current record until box
  4196.                                     filled, End Of File or .NOT. &condition.
  4197.  
  4198.  
  4199.        Usage:
  4200.  
  4201.             PICKREC is mainly used as an interface for selecting a record from
  4202.             the currently selected (and FILTERed) database in order to perform
  4203.             some other action.  In the example below, PICKREC acts as the
  4204.             means for selecting records to edit, and also for adding and
  4205.             deleting records by pressing the Insert and Delete keys.
  4206.  
  4207.  
  4208.        Behavior:
  4209.  
  4210.             PICKREC skips forward and backward through the database records as
  4211.             the up and down arrow keys are pressed.  The PgUp and PgDn scroll
  4212.             one window full of records.  When the Enter key is pressed,
  4213.             PICKREC exits with the record pointer positioned at the selected
  4214.             record.  If the Escape Key is pressed, the record pointer is at
  4215.             the last displayed record, but PICKREC returns zero.
  4216.  
  4217.             If the optional <condition> parameter is used, this character
  4218.             string MUST evaluate to a logical expression.  For example, to
  4219.             list all sales orders for customer code RCL100, the condition
  4220.             would be "ALIAS->CUSTNO = 'RCL100'".  Notice that strings enclosed
  4221.             in quotes are bounded by 'quotes within quotes'.  If this
  4222.             condition does not evaluate to a logical expression, a runtime
  4223.             TYPE MISMATCH error will occur.
  4224.  
  4225.  
  4226.  
  4227.        _______________________________________________________________________
  4228.        RLIB 2.0                                                             72
  4229.  
  4230.  
  4231.             When using conditions, it is important to position the record
  4232.             pointer to the first record meeting this condition before first
  4233.             calling PICKREC.  PICKREC cannot assume any index files are open
  4234.             and therefore cannot find the first logical record short of doing
  4235.             a LOCATE FOR.. command.  Since this would be prohibitively slow,
  4236.             PICKREC assumes the record pointer is at the first logical record
  4237.             upon entry (with rownumber = 0).  Upon re-entry with rownumber
  4238.             being less than zero, PICKREC will SKIP BACKWARD to find the first
  4239.             logical record meeting <condition>.
  4240.  
  4241.             PICKREC uses the current color setting for display of the records
  4242.             in the window.  The color used for the selection bar is the
  4243.             Enhanced setting, which is the same color used for active GETs. 
  4244.             After selection of a record, that selection is displayed in bright
  4245.             standard color (the standard color with a '+' placed after the
  4246.             color letter).
  4247.  
  4248.             If the field list expression display is wider that the width of
  4249.             the display box, it is truncated; if it is shorter, spaces are
  4250.             added onto the end to make the selection bar as wide as the box.
  4251.  
  4252.  
  4253.        Example #1:
  4254.  
  4255.             *-- set up a memvar for holding the row number and set it to 0
  4256.             rownum = 0
  4257.  
  4258.             *-- PICKREC assumes you are in the desired work area
  4259.             SELECT Fonebook
  4260.  
  4261.             *-- allow the Insert and Delete keys to force an exit
  4262.             keys = CHR(22) + CHR(7)
  4263.  
  4264.             *-- establish a character string of what you want displayed
  4265.             *-- this will look like ==> LOW, RICHARD C.   - (301) 377-8529
  4266.             string = "Lastname + ', ' + Firstname + ' - ' + Fonenumber"
  4267.  
  4268.             *-- draw a double line box with a title header
  4269.             @ 4,40,23,79 BOX '        '
  4270.             @ 5,41 SAY  '       AVAILABLE PHONE LISTINGS       '
  4271.             @ 6,40 SAY '                                        '
  4272.  
  4273.             DO WHILE .T.
  4274.                *-- now present records from database to choose from
  4275.                rownum = PICKREC( 7, 41, 22, 78, string, rownum, "", keys )
  4276.  
  4277.                DO CASE
  4278.                   CASE rownum = 0      && Escape returns 0
  4279.                      EXIT
  4280.  
  4281.                   CASE LASTKEY() = 22  && Insert Key - add a record
  4282.                      MEMORIZE(.T.)     && Initialize empty structure
  4283.                      DO edit_proc      && perform edits on new entry
  4284.                      rownum = -1       && must force screen refresh with -1
  4285.  
  4286.        _______________________________________________________________________
  4287.        RLIB 2.0                                                             73
  4288.  
  4289.  
  4290.  
  4291.                   CASE LASTKEY() = 7   && Delete Key
  4292.                      IF BOXASK('W/R','Are you sure? (Y/N)') = 'Y'
  4293.                         DELETE
  4294.                         rownum = 0     && start over at top of file
  4295.                      ENDIF
  4296.  
  4297.                   CASE LASTKEY() = 13  && Enter Key - edit record
  4298.                      *-- get controlling index key expression if any
  4299.                      ntx_key = NTXKEYVAL()
  4300.  
  4301.                      DO edit_proc
  4302.  
  4303.                      *-- now see if edits changed an index key value
  4304.                      IF .NOT. ntx_key == NTXKEYVAL()
  4305.                         *-- field contents changed from before edits
  4306.                         *-- must refresh screen so order is in sync
  4307.                         rownum = -1
  4308.                      ENDIF
  4309.  
  4310.                ENDCASE
  4311.             ENDDO
  4312.  
  4313.  
  4314.  
  4315.        Example #2:
  4316.  
  4317.  
  4318.             *-- use PICKREC() to provide pop-up help in field edits
  4319.             SET KEY -1 TO PopUpHelp           && F2 key is pop-up help
  4320.  
  4321.  
  4322.             mzip = SPACE(5)
  4323.             @ 10,0 SAY 'Enter zip code (press F2 for listing)';
  4324.                    GET mzip PICTURE '#####'
  4325.             READ
  4326.  
  4327.             .
  4328.             .
  4329.             .
  4330.             .
  4331.  
  4332.  
  4333.             PROCEDURE PopUpHelp
  4334.             PARAMETERS callproc, linenum, inputvar
  4335.             PRIVATE inarea
  4336.             inarea = SELECT()
  4337.             SELECT ZipCodes
  4338.  
  4339.             @ 1,50,20,79 BOX double
  4340.             @ 2,50 SAY '       ZIP CODE LISTING       '
  4341.             @ 4,50 SAY '   ZIP  - CITY                '
  4342.             @ 5,50 SAY '                              '
  4343.  
  4344.  
  4345.        _______________________________________________________________________
  4346.        RLIB 2.0                                                             74
  4347.  
  4348.  
  4349.             IF PICKREC( 6, 51, 19, 78, "Zip + ' - ' + City" ) > 0
  4350.                mzip = ZIPCODES->ZipCode
  4351.             ENDIF
  4352.             SELECT (inarea)
  4353.             RETURN
  4354.  
  4355.  
  4356.        Source:    RL_PICKR.PRG
  4357.  
  4358.  
  4359.        See also:  MULTIMENU(), PICKFILE()
  4360.  
  4361.  
  4362.  
  4363.  
  4364.  
  4365.  
  4366.  
  4367.  
  4368.  
  4369.  
  4370.  
  4371.  
  4372.  
  4373.  
  4374.  
  4375.  
  4376.  
  4377.  
  4378.  
  4379.  
  4380.  
  4381.  
  4382.  
  4383.  
  4384.  
  4385.  
  4386.  
  4387.  
  4388.  
  4389.  
  4390.  
  4391.  
  4392.  
  4393.  
  4394.  
  4395.  
  4396.  
  4397.  
  4398.  
  4399.  
  4400.  
  4401.  
  4402.  
  4403.  
  4404.        _______________________________________________________________________
  4405.        RLIB 2.0                                                             75
  4406.  
  4407.  
  4408.  
  4409.                                      RJUSTIFY()
  4410.                                      ----------
  4411.  
  4412.  
  4413.  
  4414.        Takes a character string and moves any trailing blanks to the front of
  4415.        the string, to allow for right justification in display or printing.
  4416.  
  4417.  
  4418.        Syntax:
  4419.  
  4420.             RJUSTIFY( string )
  4421.  
  4422.  
  4423.        Returns:
  4424.  
  4425.             String with trailing blanks moved to the front of the string.
  4426.  
  4427.  
  4428.        Parameters:
  4429.  
  4430.             string........ Character string or variable to be right justified.
  4431.  
  4432.  
  4433.        Usage:
  4434.  
  4435.             Useful for displaying or printing character data that may have
  4436.             trailing blanks flush right in reports. 
  4437.  
  4438.  
  4439.        Behavior:
  4440.  
  4441.             The string returned is the same length as the one provided.
  4442.  
  4443.  
  4444.        Example:
  4445.  
  4446.             acct_num = SPACE(20)
  4447.             @ 1,0 SAY 'Enter account number:' GET acct_num
  4448.             READ
  4449.  
  4450.             *-- they entered 12-34-567890 which has 8 trailing spaces
  4451.             *-- you want it printed flush right under the page number
  4452.             *-- on an 80 column display
  4453.             @ 1,67 SAY 'Page No.: ' + STR(pageno,3,0)
  4454.             @ 1,60 SAY RJUSTIFY(acct_num)
  4455.             *-- replaces: @ 1,60+20-LEN(TRIM(acct_num)) SAY ...
  4456.  
  4457.  
  4458.        Source:    RL_RJUST.PRG
  4459.  
  4460.  
  4461.        See also:  CENTER(), SAYINBOX()
  4462.  
  4463.        _______________________________________________________________________
  4464.        RLIB 2.0                                                             76
  4465.  
  4466.  
  4467.  
  4468.                                      SAYINBOX()
  4469.                                      ----------
  4470.  
  4471.  
  4472.  
  4473.        This is similar to the BOXASK() function, but instead of waiting for a
  4474.        keypress response like BOXASK(), SAYINBOX() merely puts the message up
  4475.        on the screen.  Where a BOXASK() message disappears when a key is hit,
  4476.        SAYINBOX() messages stay (with one exception mentioned below).  Up to
  4477.        nine lines may be included, with the color used for the box being
  4478.        optional.
  4479.  
  4480.  
  4481.        Syntax:
  4482.  
  4483.             SAYINBOX( [ color, ] line1 [, line2...line9 ] [ timeout ] )
  4484.  
  4485.  
  4486.        Returns:
  4487.  
  4488.             Nothing.
  4489.  
  4490.  
  4491.        Parameters:
  4492.  
  4493.             color........  Optional variable or constant indicating the screen
  4494.                            color setting to use in the form 'W/N'.  The
  4495.                            default color is WHITE foreground on RED
  4496.                            background.
  4497.  
  4498.             line1........  Character string to be displayed within the box. 
  4499.                            The string may be up to 65 characters long.
  4500.  
  4501.             line2..9.....  Optional additional lines to be displayed.  Up to
  4502.                            nine lines may be included.
  4503.  
  4504.             timeout......  Optional numeric parameter indicating the number of
  4505.                            seconds to pause and leave the message on screen.
  4506.  
  4507.  
  4508.        Usage:
  4509.  
  4510.             An easy way to 'pop up' messages in the middle of the screen.
  4511.  
  4512.  
  4513.        Behavior:
  4514.  
  4515.             Like BOXASK(), this is one of the few functions that breaks the
  4516.             rule that says, if you want to skip a parameter, you must pass a
  4517.             dummy in its place.  In this function, the first parameter is
  4518.             evaluated to determine if it is a string to be displayed in the
  4519.             box, or if it is a color setting.  The first parameter is deemed
  4520.             to be a color setting if the 2nd, 3rd, or 4th character is the '/'
  4521.  
  4522.        _______________________________________________________________________
  4523.        RLIB 2.0                                                             77
  4524.  
  4525.  
  4526.             character.  At least one line must be specified, if the character
  4527.             string is longer than 65 characters, it is truncated.  If the
  4528.             optional timeout parameter is specified, the message will remain
  4529.             on screen for that many seconds, or until any key is pressed, then
  4530.             disappear.  This is useful for displaying error or warning
  4531.             messages for several seconds without having to require the user to
  4532.             press a key.
  4533.  
  4534.             The following defaults apply to determine how the box is
  4535.             positioned in the middle of the screen:
  4536.  
  4537.                Centering   -  The box is centered on screen from top to
  4538.                               bottom, and left to right depending on the
  4539.                               number of lines and the widest line.  One blank
  4540.                               line is placed above and below the first and
  4541.                               last line to be displayed, and five spaces are
  4542.                               placed in front of and trailing the widest line
  4543.                               to be displayed.  Each line is centered within
  4544.                               the box.
  4545.  
  4546.                Environment -  The screen below the box, the current color
  4547.                               setting, and the cursor position are saved and
  4548.                               restored on exit if the optional timeout is
  4549.                               specified.  In other words, the box disappears
  4550.                               and you are left where you were.
  4551.  
  4552.  
  4553.        Examples:
  4554.  
  4555.             *-- if an index search fails, notify the user and wait 6 seconds
  4556.             SEEK mname
  4557.             IF .NOT. FOUND()
  4558.                line1 = 'No records found under ' + mname
  4559.                line2 = 'Search terminated!'
  4560.                *-- use a warning color Bright White on Brown
  4561.                SAYINBOX( 'W+/GR', line1, line2, 6 )
  4562.                LOOP
  4563.             ENDIF
  4564.  
  4565.  
  4566.        Source:    RL_SAYIN.PRG
  4567.  
  4568.  
  4569.        See also:  BOXASK()
  4570.  
  4571.  
  4572.  
  4573.  
  4574.  
  4575.  
  4576.  
  4577.  
  4578.  
  4579.  
  4580.  
  4581.        _______________________________________________________________________
  4582.        RLIB 2.0                                                             78
  4583.  
  4584.  
  4585.  
  4586.                                      STR2DATE()
  4587.                                      ----------
  4588.  
  4589.  
  4590.  
  4591.        To convert a date string in the form of either Jan 1, 1987 or January
  4592.        1, 1987 to a date type variable.
  4593.  
  4594.  
  4595.        Syntax:
  4596.  
  4597.             STR2DATE( datestring )
  4598.  
  4599.  
  4600.        Returns:
  4601.  
  4602.             A date variable corresponding to the date supplied in the string. 
  4603.             If the string is in an invalid format, an empty date ('  /  /  ')
  4604.             is returned.
  4605.  
  4606.  
  4607.        Parameters:
  4608.  
  4609.             datestring.... The date string to be converted.  String must be in
  4610.                            the form 'Jan 1, 1987' or 'January 31, 1987'.
  4611.  
  4612.  
  4613.        Usage:
  4614.  
  4615.             Several software packages store dates in the character string
  4616.             format Sep 10, 1987.  This function is useful for parsing these
  4617.             strings when importing data and translating into a date type
  4618.             field.
  4619.  
  4620.  
  4621.        Example:
  4622.  
  4623.             *-- get data from import text file from other software
  4624.             APPEND FROM textfile DELIMITED
  4625.  
  4626.             *-- date string is in field named StringDate
  4627.  
  4628.             *-- convert date in form Sep 10, 1988 to date variable
  4629.             REPLACE Startdate WITH STR2DATE(Stringdate)
  4630.  
  4631.  
  4632.        Source:    RL_STR2D.PRG
  4633.  
  4634.  
  4635.        See also:  ALPHADATE()
  4636.  
  4637.  
  4638.  
  4639.  
  4640.        _______________________________________________________________________
  4641.        RLIB 2.0                                                             79
  4642.  
  4643.  
  4644.  
  4645.                                      APPENDIX A
  4646.  
  4647.                                 RLIB QUICK REFERENCE
  4648.                                 ====================
  4649.  
  4650.  
  4651.  
  4652.             ALPHADATE( [date] )
  4653.  
  4654.                   Convert a date variable to date character string.
  4655.  
  4656.             ATINSAY( row, column, color, string )
  4657.  
  4658.                   At a given screen coordinate SAY an expression IN the color
  4659.                   setting provided.
  4660.  
  4661.             BARMENU( row, options [,columns [,choice [,altkeys [,exitkeys;
  4662.                      [,prompts [,prompt_row [,colors ]]]]]] )
  4663.  
  4664.                   Create Lotus 123 style light bar menus.
  4665.  
  4666.             BEEP( [number] )
  4667.  
  4668.                   Ring the system bell multiple times.
  4669.  
  4670.             BOXASK( [color,] line1 [,line2 .... ,line9] [,timeout] )
  4671.  
  4672.                   Pop up a dialogue box in the center of the screen to get
  4673.                   user response.
  4674.  
  4675.             BOXMENU( row, column, options [, choice [, altkeys [, exitkeys;
  4676.                     [, prompts [, prompt_row [, colors ]]]]]] )
  4677.  
  4678.                   Create 'boxed' menus with total control!
  4679.  
  4680.             BRIGHT( [color] )
  4681.  
  4682.                   Get the bright version of the current or indicated color.
  4683.  
  4684.             CENTER( [ row, ] string )
  4685.  
  4686.                   Determine the column position to center text on an 80 column
  4687.                   display, optionally displaying it.
  4688.  
  4689.             CHANGED()
  4690.  
  4691.                   Determine if field memory variables were changed during an
  4692.                   edit.
  4693.  
  4694.             CLOSEAREA( [ work_area, work_area ... ] )
  4695.  
  4696.                   Close multiple database work areas with one command.
  4697.  
  4698.  
  4699.        _______________________________________________________________________
  4700.        RLIB 2.0                                                             80
  4701.  
  4702.  
  4703.  
  4704.             DECRYPTED( string )
  4705.  
  4706.                   Un-encrypt a character string encrypted with ENCRYPTED().
  4707.  
  4708.             ENCRYPTED( string )
  4709.  
  4710.                   Encrypt a character string.
  4711.  
  4712.             FILEDATE( filename )
  4713.  
  4714.                   Get the last update date for a file.
  4715.  
  4716.             FILES( filename [, filename...filename ] )
  4717.  
  4718.                   Determine if multiple files exist with one function.
  4719.  
  4720.             FILETIME( filename )
  4721.  
  4722.                   Get the last update time for a file.
  4723.  
  4724.             FORGET()
  4725.  
  4726.                   Release field memory variables created with MEMORIZE().
  4727.  
  4728.             GETPARM( position, string )
  4729.  
  4730.                   Retrieve a comma delimited parameter from a character
  4731.                   string.
  4732.  
  4733.             KEYINPUT( length, upper_case, echo_chars )
  4734.  
  4735.                   Get keyboard input while echoing dots on the screen.
  4736.  
  4737.             MARKREC( top, left, bottom, right, output [, markkey 
  4738.                      [, markfield [,colors ] ] ] )
  4739.  
  4740.                   Select multiple database records to process from a pop-up
  4741.                   selection window.
  4742.  
  4743.             MEMORIZE( [ blank ] )
  4744.  
  4745.                   Save all field values to memory variables for edit.
  4746.  
  4747.             MREPLACE()
  4748.  
  4749.                   Replace database fields with field memory variables created
  4750.                   with MEMORIZE().
  4751.  
  4752.             MULTIMENU( top, left, bottom, right, options [, columns ;
  4753.                        [, messages [, message_row [, colors ] ] ] ] )
  4754.  
  4755.                   Create multi-column menus allowing left, right, up, and down
  4756.                   cursor movement to select.
  4757.  
  4758.        _______________________________________________________________________
  4759.        RLIB 2.0                                                             81
  4760.  
  4761.  
  4762.  
  4763.             NAMESPLIT( name )
  4764.  
  4765.                   Convert names from First Middle Last to Last, First Middle.
  4766.  
  4767.             NTXKEYVAL()
  4768.  
  4769.                   Get the controlling index key value for the current record.
  4770.  
  4771.             PARENT( [directory] )
  4772.  
  4773.                   Get the parent directory name for the current or supplied
  4774.                   directory.
  4775.  
  4776.             PATHTO( filename )
  4777.  
  4778.                   Search the DOS path for the path leading to a given
  4779.                   filename.
  4780.  
  4781.             PDOWNINIT( [ row, columns, menus, items, startnums [,prompts ;
  4782.                         [,promptrow [,colors [,altkeys [,exit ]]]]] ] )
  4783.  
  4784.                   Initialize for PDOWNMENU().
  4785.  
  4786.             PDOWNMENU( @menu, @item, menus, items, columns, startnums;
  4787.                         [, prompts [, exit ] ] ) 
  4788.  
  4789.                   Create 'Pull Down' menus.
  4790.  
  4791.             PICKFILE( [ filespec [, top, left, bottom [, colors;
  4792.                       [, expanded ] ] ] ] )
  4793.  
  4794.                   Pop up a file directory listing to pick a file and return
  4795.                   the filename.
  4796.  
  4797.             PICKREC( top, left, bottom, right, fieldlist, [, procname;
  4798.                      [, condition [, rownumber ] ] ] )
  4799.  
  4800.                   Pop up a menu of database records from which to pick a
  4801.                   record.
  4802.  
  4803.             RJUSTIFY( string )
  4804.  
  4805.                   Right justify character strings by moving trailing blanks to
  4806.                   the front.
  4807.  
  4808.             SAYINBOX( [ color, ] line1 [, line2...line9 ] [ timeout ] )
  4809.  
  4810.                   Display messages in center of the screen in a dialogue box.
  4811.  
  4812.             STR2DATE( datestring )
  4813.  
  4814.                   Convert dates in the form January 31, 1988 to 01/31/88.
  4815.  
  4816.  
  4817.        _______________________________________________________________________
  4818.        RLIB 2.0                                                             82
  4819.  
  4820.